Paypal Gateway 2012 Developers Guide Developer And Reference

Gateway - 2012 - Developer Guide and Reference PP_PayflowGateway_2012 Free User Guide for PayPal Software, Manual

2015-07-27

: Paypal Paypal-Gateway-2012-Developers-Guide-777943 paypal-gateway-2012-developers-guide-777943 paypal pdf

Open the PDF directly: View PDF .
Page Count: 230 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Content
Preface
Introducing the Gateway Checkout Solutions
Secure Token
Configuring Hosted Checkout Pages
Payflow SDK
Sending a Simple Transaction to the Server
Submitting Credit Card Transactions
Testing Transactions
Transaction Responses
Processors Requiring Additional Transaction Parameters
TeleCheck Electronic Check Processing
Submitting Purchasing Card Level 2 and Level 3 Transactions
VERBOSITY: Viewing Processor- Specific Transaction Results
ISO Country Codes
Codes Used by FDMS South Only
PayPal Acquirer
- Countries and Regions Supported by PayPal
- PayPal Currency Codes
Additional Processor Information
- Moneris Solutions
Payflow Link Migration
- Migrating from a legacy Payflow Link Integration

Gateway Developer

Guide and Reference

PayPal Payments Advanced

PayPal Payments Pro

Payflow Pro

Payflow Link

Last updated: 31 July 2012

Gateway Developer Guide and Reference

Document Number: 200045.en_US-20120731

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.

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 in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,

implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused

by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use

of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.

Gateway Developer Guide and Reference 31 July 2012 3

Content

Chapter P Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Who Should Use This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Chapter 1 Introducing the Gateway Checkout Solutions . . . . . . . .19

About the Gateway Checkout Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Summary of the Gateway Checkout Solutions . . . . . . . . . . . . . . . . . . . . . 19

Gateway Product Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

About the Gateway Transaction Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

About Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Secure Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Hosted Checkout Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

PCI Compliance Without Hosted Pages: Transparent Redirect . . . . . . . . . . . . . 24

Processing Platforms Supporting Card-Present Transactions . . . . . . . . . . . . . . . . 24

Supported Payment Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Recurring Billing Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Chapter 2 Secure Token . . . . . . . . . . . . . . . . . . . . . . . .27

About the Secure Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Integrating the Secure Token With the Hosted Checkout Pages . . . . . . . . . . . . . . 27

Integrating the Secure Token Without the Hosted Checkout Pages: Transparent Redirect . 28

Posting To the Hosted Checkout Page . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Chapter 3 Configuring Hosted Checkout Pages . . . . . . . . . . . .31

Configuring Hosted Checkout Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Configuring Hosted Pages Using PayPal Manager . . . . . . . . . . . . . . . . . . . . . 31

Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Customize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Content

431 July 2012 Gateway Developer Guide and Reference

Using a Secure Token and Dynamically Passing Form Post Variables . . . . . . . . . . . 36

Silent Posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Force Silent Post Confirmation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Data Returned by the Silent Post Features . . . . . . . . . . . . . . . . . . . . . . . 39

Chapter 4 Payflow SDK . . . . . . . . . . . . . . . . . . . . . . . . .41

Preparing the Payflow Gateway Client Application . . . . . . . . . . . . . . . . . . . . . 41

Activating Your Payflow Gateway Account. . . . . . . . . . . . . . . . . . . . . . . . . . 42

Host URL Addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Chapter 5 Sending a Simple Transaction to the Server . . . . . . . .43

About Name-Value Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Using Special Characters In Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Name-Value Parameter Syntax Guidelines . . . . . . . . . . . . . . . . . . . . . . . 44

Do Not URL Encode Name-Value Parameter Data . . . . . . . . . . . . . . . . . . . 44

Payflow Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

User Parameter Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Sale Transaction Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Typical Sale Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Formatting Payflow Gateway Transactions . . . . . . . . . . . . . . . . . . . . . . . . . 46

Chapter 6 Submitting Credit Card Transactions . . . . . . . . . . . .47

Obtaining an Internet Merchant Account . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

About Credit Card Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Credit Card Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Planning Your Gateway Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Complying With E-commerce Indicator . . . . . . . . . . . . . . . . . . . . . . . . . 50

Handling Credit Card Type Information . . . . . . . . . . . . . . . . . . . . . . . . . 50

Core Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Submitting Account Verifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

When To Use Account Verifications . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Required Account Verification Parameters . . . . . . . . . . . . . . . . . . . . . . . 54

Example Account Verification String . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Submitting Authorization/Delayed Capture Transactions . . . . . . . . . . . . . . . . . . 55

When to Use Authorization/Delayed Capture Transactions . . . . . . . . . . . . . . . 55

Required Authorization Transaction Parameters . . . . . . . . . . . . . . . . . . . . 56

Typical Authorization Transaction Parameter String . . . . . . . . . . . . . . . . . . . 56

Gateway Developer Guide and Reference 31 July 2012 5

Content

Submitting Balance Inquiry Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Processing Platforms Supporting Balance Inquiry Transactions . . . . . . . . . . . . 56

Required Balance Inquiry Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Example Balance Inquiry Transaction String . . . . . . . . . . . . . . . . . . . . . . 57

Submitting Card Present (SWIPE) Transactions. . . . . . . . . . . . . . . . . . . . . . . 57

Processing Platforms Supporting Card-Present Transactions. . . . . . . . . . . . . . 58

Card Present Transaction Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Submitting Credit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Required Credit Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . 59

Submitting Inquiry Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

When To Use an Inquiry Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Required Parameters When Using the PNREF . . . . . . . . . . . . . . . . . . . . . 61

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

Required Parameters When Using the CUSTREF . . . . . . . . . . . . . . . . . . . 62

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

Required Parameters When Using the Secure Token . . . . . . . . . . . . . . . . . . 63

Inquiry Parameter String Using the Secure Token . . . . . . . . . . . . . . . . . . . . 63

Submitting Partial Authorizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

When To Use Partial Authorizations . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Required Partial Authorization Parameters . . . . . . . . . . . . . . . . . . . . . . . 64

Example Partial Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Submitting Purchasing Card Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Submitting Reference Transactions (Tokenization) . . . . . . . . . . . . . . . . . . . . . 66

When To Use a Reference Transaction . . . . . . . . . . . . . . . . . . . . . . . . . 66

Transaction Types That Can Be Used As the Original Transaction . . . . . . . . . . . 66

Fields Copied From Reference Transactions . . . . . . . . . . . . . . . . . . . . . . 67

Example Reference Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Data Upload - Storing Credit Card Data on the Gateway Server . . . . . . . . . . . . 68

Submitting Sale Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

When To Use a Sale Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Additional Parameters For Sale Transactions . . . . . . . . . . . . . . . . . . . . . . 69

Typical Sale Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . . 69

Submitting Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

About Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Ways to Send Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . 70

Submitting Voice Authorization Transactions . . . . . . . . . . . . . . . . . . . . . . . . 71

When To Use a Voice Authorization Transaction . . . . . . . . . . . . . . . . . . . . 72

Required Voice Authorization Transaction Parameters . . . . . . . . . . . . . . . . . 72

Submitting Void Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Content

631 July 2012 Gateway Developer Guide and Reference

When To Use a Void Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Required Void Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 73

Fields Copied From the Original Transaction Into the Void Transaction. . . . . . . . . 73

Example Void Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . 74

Using Address Verification Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Example Address Verification Service Parameter String . . . . . . . . . . . . . . . . 74

Using Card Security Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Chapter 7 Testing Transactions . . . . . . . . . . . . . . . . . . . .77

Setting Up The Payflow Gateway Testing Environment . . . . . . . . . . . . . . . . . . . 77

Testing Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Processors Other Than PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Credit Card Numbers for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Testing Address Verification Service. . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Testing Card Security Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

PayPal Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Credit Card Numbers for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Result Values Based On Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Chapter 8 Transaction Responses . . . . . . . . . . . . . . . . . . .87

Credit Card Transaction Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Address Verification Service Responses From PayPal . . . . . . . . . . . . . . . . . . . 90

Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Normalized Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . 92

PayPal Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

BALAMT Response and Stored Value Cards . . . . . . . . . . . . . . . . . . . . . . . . 93

American Express Stored Value Card Example . . . . . . . . . . . . . . . . . . . . . 93

PNREF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

RESULT Values and RESPMSG Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

RESULT Values For Communications Errors . . . . . . . . . . . . . . . . . . . . . .100

Chapter A Processors Requiring Additional Transaction Parameters 103

American Express Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . .103

Retail Transaction Advice Addendum (for SWIPE transactions) . . . . . . . . . . . .103

Internet Transaction Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104

Address Verification Service Parameters . . . . . . . . . . . . . . . . . . . . . . . .105

Location Transaction Advice Addendum Parameters . . . . . . . . . . . . . . . . . .105

Gateway Developer Guide and Reference 31 July 2012 7

Content

Transaction Advice Detail Parameters. . . . . . . . . . . . . . . . . . . . . . . . . .107

Airline Passenger Data Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .107

American Express Other Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .108

Elavon Additional Credit Card Parameters. . . . . . . . . . . . . . . . . . . . . . . . . .109

First Data Merchant Services Nashville, Additional Credit Card Parameters . . . . . . . . 110

First Data Merchant Services North, Additional Credit Card Parameters . . . . . . . . . .110

Heartland, Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . 111

Litle Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

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

Paymentech Salem (New Hampshire) Additional Credit Card Parameters for American

Express . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Internet Transaction Data Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .113

AVS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Additional Credit Card Parameters for M Record . . . . . . . . . . . . . . . . . . . . 115

PayPal Credit Card Transaction Request Parameters . . . . . . . . . . . . . . . . . . . . 115

SecureNet Additional Credit Card Parameters for American Express . . . . . . . . . . . .120

Retail Transaction Advice Addendum (for SWIPE transactions) . . . . . . . . . . . .120

Internet Transaction Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121

AVS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121

Location Transaction Advice Addendum Parameters . . . . . . . . . . . . . . . . . .122

Transaction Advice Detail Parameters. . . . . . . . . . . . . . . . . . . . . . . . . .123

Airline Passenger Data Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .123

Other Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125

Vantiv Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .125

Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .125

Soft Merchant Descriptor Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .126

WorldPay Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . .127

Chapter B TeleCheck Electronic Check Processing . . . . . . . . . 129

TeleCheck NFTF Overview of Services . . . . . . . . . . . . . . . . . . . . . . . . . . .129

TeleCheck NFTF Processing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . .129

NFTF Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129

NFTF Processing Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . .131

NFTF Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131

TeleCheck Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132

Required TeleCheck Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .133

Testing TeleCheck Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135

Example Test Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135

Content

831 July 2012 Gateway Developer Guide and Reference

Preparing for TeleCheck Production Transactions . . . . . . . . . . . . . . . . . . . . . .136

Responses to TeleCheck Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . .136

Transaction Responses Common to All Tender Types . . . . . . . . . . . . . . . . .136

Response Code Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137

Sale Response Code Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137

Adjustment Code Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138

Response Codes For Status Response Packets . . . . . . . . . . . . . . . . . . . .138

TeleCheck Authorization Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . .139

Authorization – Sales Consent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139

Authorization – Sales Decline/Error . . . . . . . . . . . . . . . . . . . . . . . . . . .142

Chapter C Submitting Purchasing Card Level 2 and Level 3 Transactions

143

About Purchasing Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143

About Program Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143

Accepted BIN Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144

About American Express Purchasing Card Transactions . . . . . . . . . . . . . . . . . .144

Supported Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144

Avoiding Downgrade. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145

Submitting Successful Level 3 Transactions . . . . . . . . . . . . . . . . . . . . . .145

Edit Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145

Accepted BIN Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

American Express Purchasing Card Transaction Processing . . . . . . . . . . . . . . . .146

American Express Level 2 Parameters for American Express . . . . . . . . . . . . .146

Example American Express Level 2 Transaction Parameter String . . . . . . . . . . .149

American Express Level 3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . .149

Example American Express Level 3 Transaction Parameter String . . . . . . . . . . .151

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

Elavon Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152

Elavon Additional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152

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

First Data Merchant Services (FDMS) Nashville Purchasing Card Transaction Processing.153

FDMS Nashville Commercial Card Parameters . . . . . . . . . . . . . . . . . . . . .153

First Data Merchant Services (FDMS) North Purchasing Card Transaction Processing . .154

FDMS North Purchasing Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .154

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

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

FDMS South Level 2 and Level 3 Purchasing Card Parameters . . . . . . . . . . . .156

FDMS South Line Item Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .157

Gateway Developer Guide and Reference 31 July 2012 9

Content

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

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

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

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

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

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

Example Global Payments - East Level 2 Visa or MasterCard Transaction Parameter String

160

Heartland Purchasing Card Transaction Processing. . . . . . . . . . . . . . . . . . . . .160

Heartland Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160

Heartland Level 3 MasterCard Parameters . . . . . . . . . . . . . . . . . . . . . . .161

Heartland Level 3 Visa Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .163

Litle Purchasing Card Transaction Processing. . . . . . . . . . . . . . . . . . . . . . . .166

Litle Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166

Litle Level 3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167

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

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

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

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

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

Paymentech Salem (New Hampshire) Level 2 Parameters for American Express . . .174

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

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

Paymentech Tampa Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . .181

Example Paymentech Tampa Level 2 Visa and MasterCard Transaction Parameter String

181

SecureNet Purchasing Card Transaction Processing . . . . . . . . . . . . . . . . . . . .181

SecureNet Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181

SecureNet Level 3 MasterCard Parameters . . . . . . . . . . . . . . . . . . . . . . .182

SecureNet Acquiring Solutions Level 3 Visa Parameters . . . . . . . . . . . . . . . .184

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

TSYS Acquiring Solutions Level 2 Parameters . . . . . . . . . . . . . . . . . . . . .187

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

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

Vantiv Purchasing Card Transaction Processing . . . . . . . . . . . . . . . . . . . . . .193

Vantiv Purchasing Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193

Vantiv Purchasing Card Line Item Parameters . . . . . . . . . . . . . . . . . . . . .193

WorldPay Purchasing Cards Transaction Processing . . . . . . . . . . . . . . . . . . . .194

WorldPay Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194

WorldPay Level 3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196

Content

10 31 July 2012 Gateway Developer Guide and Reference

Chapter D VERBOSITY: Viewing Processor-Specific Transaction Results

199

Chapter E ISO Country Codes . . . . . . . . . . . . . . . . . . . . 201

Chapter F Codes Used by FDMS South Only . . . . . . . . . . . . . 203

MasterCard Country Codes for FDMS South Only . . . . . . . . . . . . . . . . . . . . .203

Visa Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .210

Units of Measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217

Chapter G PayPal Acquirer . . . . . . . . . . . . . . . . . . . . . . 225

Countries and Regions Supported by PayPal . . . . . . . . . . . . . . . . . . . . . . . .225

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225

PayPal Currency Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225

Chapter H Additional Processor Information . . . . . . . . . . . . . 227

Moneris Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227

Chapter I Payflow Link Migration . . . . . . . . . . . . . . . . . . 229

Migrating from a legacy Payflow Link Integration . . . . . . . . . . . . . . . . . . . . . .229

Gateway Developer Guide and Reference 31 July 2012 11

PPreface

This guide describes the data parameters for the Gateway payments solutions.

Scope

This guide is a reference to the payment card data parameters available for submitting in

transaction requests over the Gateway to multiple supported processors. It also covers the

resulting response data parameters and errors.

The guide describes the requirements of an ever growing list of processing platforms. It

organizes parameters into a core set of request parameters supported by all processors,

additional parameters unique to individual processors, and purchasing card parameters

specialized to monitor credit card use in businesses. It also provides a section on response

parameters and error codes (PNREF values that are not 0).

Although this guide provides guidance on getting started with the SDK, setting up credit card

processing, and testing your integration, its broad scope does not lend to use as a tutorial on

integration. Refer to the PayPal Developer website and the Payflow Gateway SDK for detailed

working examples and use cases.

Other HTML Post Params

SILENTPOSTFAILEDURL The return URL when Silent Post fails. Maximum

length: 255 characters.

TEMPLATE Determines whether to use one of the two redirect

templates (Layout A or B) or the embedded template C.

Values are: TEMPLATEA or TEMPLATEB or MINLAYOUT

(for template C)

URLMETHOD The technical method used to deliver the CANCELURL.

The default is GET and cannot be changed without

affecting the installed base, but this value will likely be

changed to Post by most carts. Values: POST or GET

Variable Description

PAGECOLLAPSEBGCOLOR Sets the color of the border around the embedded

template C. Example:

PAGECOLLAPSEBGCOLOR=993300

PAGECOLLAPSETEXTCOLOR Sets the color of the words “Pay with PayPal” and “Pay

with credit or debit card”. Example:

PAGECOLLAPSETEXTCOLOR=990000

PAGEBUTTONBGCOLOR Sets the color of the Pay Now / Submit button.

Example: PAGEBUTTONBGCOLOR=AA66FF

PAGEBUTTONTEXTCOLOR Sets the color of the text on the Pay Now / Submit

button. Example: PAGEBUTTONTEXTCOLOR=33FFFF

LABELTEXTCOLOR Sets the color of the text for “card number”, “expiration

date”, ..etc. Example: LABELTEXTCOLOR=330000

Variable Description

MODE (Optional) Used in conjunction with secure token. It lets

Payflow know that the secure token passed in is a live

or test token.Values: LIVE/TEST. Default is LIVE.

PARMLIST Used with a secure token. Passing in a string such as

PARMLIST=COMMENT1=Test&COMMENT2=Test2&US

ER1=123456 will make it so that Payflow will parse

out the name-value pairs and use those to run

thetransaction as well. This is for merchants that

alreadyhave an existing PARMLIST they would be using

withthe Payflow SDK and want an easy integration.

SECURETOKEN/SECURETOKENID Used with the secure token.

Variable Description

Configuring Hosted Checkout Pages

Silent Posts

38 31 July 2012 Gateway Developer Guide and Reference

Silent Posts

The Silent Post feature returns data to your server using the HTML Post method whenever a

transaction succeeds. The data is sent at the same time as when the Receipt page is displayed.

This feature is configured through https://manager.paypal.com:

-Go to Service Settings, then Setup

-In the Hosted Checkout Pages tab, set Use Silent Post to Yes

NOTE:To ensure that transactions proceed only if your script actually receives the data

returned by the Silent Post, you must Force Silent Post Confirmation by checking Voi d

transaction when my server fails to receive data sent by the silent post.

Force Silent Post Confirmation

The Force Silent Post Confirmation feature ensures that no transactions proceed unless your

Web site receives the Silent Post data.If you enable this feature, Payflow Gateway sends the

Silent Post data and waits for a 200 OK from your server (indicating the server’s receipt of the

data). If Payflow Gateway does not receive the success response, then the transaction is voided

and the customer sees a communication error message. In this case, PayPal Manager displays

both a transaction that succeeded and a transaction that was voided. To select this feature, be

sure to check Void transaction when my server fails to receive data sent by the silent post when

setting up Silent Posts in PayPal Manager.

SHOWAMOUNT If you pass in $0 amount and trans type = A, then if

SHOWAMOUNT=FALSE, Payflow will not display the

amount in the order summary table.Values:

TRUE/FALSE

SUBTOTAL Amount you pass to Payflow. It is displayed in the order

summary section. This amount is only for display

purposes and is not passed to the transaction servers.

VERBOSITY Additional values that is returned from the transaction

response to the merchant in the Silent Post. By default,

there is no verbosity set which means the standard set of

values that Silent Post currently uses is returned.

Passing in a verbosity will return the extra values that

we get back in the transaction response.Value: HIGH

VERIFY Runs a $0 authorization transaction using the credit card

information the buyer enters. If the $0 authorization is

verified, then Payflow will immediately run the

transaction for the amount and transaction type you pass

to Payflow.Values: TRUE/FALSE

Variable Description

Gateway Developer Guide and Reference 31 July 2012 39

Configuring Hosted Checkout Pages

Silent Posts 3

Data Returned by the Silent Post Features

The Silent Post feature returns either a short list of data or all of the data that was submitted for

the transaction. You can control what is returned to you via the optional ECHODATA parameter:

-To return a short list of values generated by PayPal and the issuing bank which provide

status information on the submitted transaction, set the optional ECHODATA parameter to

False. This will return the same values that you receive in a typical transaction response.

(See Transaction Responses for more info).

-To return both the short list of generated values plus all of the transaction data that was

submitted for the transaction, set the optional ECHODATA parameter to True. This is the

default setting. This will return the name and address parameters that were provided in the

request in addition to the values that you receive in a typical transaction response. (See

Transaction Responses for more info).

Configuring Hosted Checkout Pages

Silent Posts

40 31 July 2012 Gateway Developer Guide and Reference

Gateway Developer Guide and Reference 31 July 2012 41

4Payflow SDK

The Payflow Software Development Kit (SDK) is a set of APIs to allow you to integrate the

Gateway with your application or website. This section includes:

-“Preparing the Payflow Gateway Client Application” on page 41.

-“Activating Your Payflow Gateway Account” on page 42.

-“Host URL Addresses” on page 42

NOTE:Each SDK includes full API documentation.

The Payflow SDK is available as a .NET or Java library.

NOTE:Alternately you can build your own API by posting directly to the Gateway servers by

HTTPS. Any reference to Payflow SDK or API in this documentation is referred to

simply as the Payflow SDK.

Preparing the Payflow Gateway Client Application

Unless you are building your own API and using HTTPS to post to the servers, you need to

obtain the Payflow SDK. Follow these steps.

1. Download the Payflow SDK.

From the SDKs and Downloads page on x.com, 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 Gateway request, 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 client application in your development environment.

Payflow SDK

Activating Your Payflow Gateway Account

42 31 July 2012 Gateway Developer Guide and Reference

Activating Your Payflow Gateway Account

When you are ready to activate your Gateway account to begin submitting live transactions,

follow these steps:

1. Log in to PayPal Manager at https://manager.paypal.com

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 Gateway

server host addresses.

Host URL Addresses

Use the following host addresses for sending test and live transactions:

-For live transactions, use https://payflowpro.paypal.com

-For testing purposes, use https://pilot-payflowpro.paypal.com

Gateway Developer Guide and Reference 31 July 2012 43

5Sending a Simple Transaction to

the Server

When using the Payflow SDK, you send transactions to the Gateway server in name-value pair

format. Typically, a simple transaction includes connection parameters, user parameters, and

transaction data parameters.

-“About Name-Value Pairs” on page 43

-“Payflow Connection Parameters” on page 44

-“User Parameter Data” on page 45

-“Sale Transaction Example” on page 46

-“Formatting Payflow Gateway Transactions” on page 46

About Name-Value Pairs

Name-value pair (NVP) is the format you use to specify the parameter information you send in

a transaction request to the Payflow server. A name-value pair consists of the parameter name

and its value. The equal sign (=) is a special character that associates the name and its value:

PARAMNAME=value

Typically, you send several name-value pairs as a parameter string to the server. The

ampersand (&) is a special character that separates each name-value pair in the parameter

string:

PARAM1NAME=value&PARAM2NAME=value&PARAM3NAME=value

Follow the special character and syntax guidelines when creating name-value pairs.

Using Special Characters In Values

Because the ampersand (&) and equal sign (=) characters have special meanings, they are

invalid in a name-value pair value.

The following are invalid:

COMPANYNAME=Ruff & Johnson

COMMENT1=Level=5

To include special characters in the value portion 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 are valid.

Sending a Simple Transaction to the Server

Payflow Connection Parameters

44 31 July 2012 Gateway Developer Guide and Reference

COMPANYNAME[14]=Ruff & Johnson

COMMENT1[7]=Level=5

NOTE:Do not use quotation marks ("") even if you use a length tag.

Name-Value Parameter Syntax Guidelines

Follow these guidelines when creating name-value pair (NVP) parameter strings:

-Do not use spaces in values.

-Enclose the NVP parameter string in quotation marks (“ “).

-Do not place quotation marks within the body of the NVP parameter string.

-Separate all NVPs using an ampersand (&).

-Set the VERBOSITY transaction parameter to HIGH to have the response return detailed

information. Act upon the returned values that you need for the transaction.

Do Not URL Encode Name-Value Parameter Data

Do not URL encode your NVP data because it can cause problems with authentication and

reporting.

This example is incorrect:

TRXTYPE%3DS%26TENDER%3DC%26USER%3DMerchantUserID%26PWD%3DPwd4Gateway%26PART

NER%3DPayPal%26ACCT%3D5105105105105100%26EXPDATE%3D1215%26AMT%3D23.45%26COM

MENT1%3DAirport+Shuttle%26BILLTOFIRSTNAME%3DJamie%26BILLTOLASTNAME%3DMiller

%26BILLTOSTREET%3D123+Main+St.%26BILLTOCITY%3DSan+Jose%26BILLTOSTATE%3DCA%2

6BILLTOZIP%3D951311234%26BILLTOCOUNTRY%3DUS%26CVV2%3D123%26CUSTIP%3D0.0.0.0

This example is correct:

TRXTYPE=S&TENDER=C&USER=MerchantUserID&PWD=Pwd4Gateway&PARTNER=PayPal&ACCT=

5105105105105100&EXPDATE=1215&AMT=23.45&COMMENT1=Airport Shuttle&BILLTOFIRS

TNAME=Jamie&BILLTOLASTNAME=Miller&BILLTOSTREET=123 Main St.&BILLTOCITY=San

Jose&BILLTOSTATE=CA&BILLTOZIP=951311234&BILLTOCOUNTRY=US&CVV2=123&CUSTIP=0.

0.0.0

Payflow Connection Parameters

The Payflow SDK passes connection parameters to define the connection to the Payflow

server.

Pass the connection parameters in the format and syntax required by the Payflow SDK and

programming language that you are using. See your integration documentation for details.

Gateway Developer Guide and Reference 31 July 2012 45

Sending a Simple Transaction to the Server

User Parameter Data 5

In addition to the connection parameters in the table, you must pass the NVP parameters that

specify the payment information for the transaction.

User Parameter Data

All Gateway transactions require the user parameters described as follows.

User paramters

Parameter Description

HOSTADDRESS (Required) Gateway server name.

HOSTPORT (Required) Use port 443.

TIMEOUT (Required) Time-out period for the transaction. PayPal recommends a minimum

time-out value of 30 seconds. The client begins tracking from the time that it

sends the transaction request to the server.

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

firewall. Your network administrator can provide the values.

PROXYPORT (Optional) Proxy server port.

PROXYLOGON (Optional) Proxy server logon ID.

PROXYPASSWORD (Optional) Proxy server logon password.

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: 64 alphanumeric, case-sensitive characters

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

account.

Limitations: 64 alphanumeric, case-sensitive characters

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

registered you for the Gateway gateway. If you purchased your account directly

from PayPal, use PayPal.

Limitations: 64 alphanumeric, case-sensitive characters

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

Limitations: 6 to 32 alphanumeric, case-sensitive characters

Sending a Simple Transaction to the Server

Sale Transaction Example

46 31 July 2012 Gateway Developer Guide and Reference

Sale Transaction Example

In addition to the required connection and user parameters, each transaction type may require

other parameters and can include a number of optional parameters.

To perform a sale transaction involving a credit card, for example, pass the following

parameters:

-TRXTYPE - The type of the transaction, such as S for Sale

-TENDER - The method of payment, such as C for credit card

-ACCT - The buyer’s credit card number

-AMT - The amount of the sale with two decimal places

-EXPDATE - The expiration date of the credit card

Typical Sale Transaction

The following is a typical name-value pair string for a sale transaction.

TRXTYPE=S&TENDER=C&USER=MerchantUserID&PWD=Pwd4Gateway&PARTNER=PayPal&ACCT=

5105105105105100&EXPDATE=1215&AMT=23.45&COMMENT1=Airport Shuttle&BILLTOFIRS

TNAME=Jamie&BILLTOLASTNAME=Miller&BILLTOSTREET=123 Main St.&BILLTOCITY=San

Jose&BILLTOSTATE=CA&BILLTOZIP=951311234&BILLTOCOUNTRY=US&CVV2=123&CUSTIP=0.

0.0.0&VERBOSITY=HIGH

Besides the required sale transaction parameters, the string includes other Payflow parameters

typically included in a sale transaction.

When the transaction completes, the Gateway server returns a response string made up of NVP

response parameters. If the transaction is successful, the Gateway server returns RESULT value

0. The value of PNREF identifies the transaction in future requests, and RESPMSG is a string

indicating whether the transaction was approved.

The following is an example response:

RESULT=0&PNREF=VXYZ01234567&RESPMSG=APPROVED&AVSADDR=Y&AVSZIP=N&IAVS=Y&CVV2

MATCH=Y

Formatting Payflow Gateway Transactions

For details on how to format a Payflow transaction, see the examples and the supporting

documentation provided with your SDK.

Gateway Developer Guide and Reference 31 July 2012 47

6Submitting Credit Card

Transactions

When using the Payflow SDK, plan how to implement credit card processing based on your

business needs. Payflow SDK offers a core set of transaction parameters that all credit card

processors use. This section describes how to submit a transaction for each transaction type

supported.

-“Obtaining an Internet Merchant Account” on page 47

-“About Credit Card Processing” on page 48

-“Credit Card Features” on page 48

-“Planning Your Gateway Integration” on page 49

-“Core Credit Card Parameters” on page 51

-“Submitting Account Verifications” on page 54

-“Submitting Authorization/Delayed Capture Transactions” on page 55

-“Submitting Balance Inquiry Transactions” on page 56

-“Submitting Card Present (SWIPE) Transactions” on page 57

-“Submitting Credit Transactions” on page 59

-“Submitting Inquiry Transactions” on page 61

-“Submitting Partial Authorizations” on page 64

-“Submitting Purchasing Card Transactions” on page 65

-“Submitting Reference Transactions (Tokenization)” on page 66

-“Submitting Sale Transactions” on page 69

-“Submitting Soft Merchant Information” on page 70

-“Submitting Voice Authorization Transactions” on page 71

-“Submitting Void Transactions” on page 72

-“Using Address Verification Service” on page 74

-“Using Card Security Code” on page 75

Obtaining an Internet Merchant Account

To accept credit cards over the internet, you need a special account called an Internet Merchant

Account. If PayPal is your merchant bank, you do not need the Internet Merchant Account.

Your account provider or merchant (acquiring) bank works with a PayPal-supported credit

card processor. Examples are First Data, TSYS Acquiring Solutions (formerly Vital

Submitting Credit Card Transactions

About Credit Card Processing

48 31 July 2012 Gateway Developer Guide and Reference

Processing Services), and Paymentech. To accept live credit cards, provide details about your

account to PayPal during the “Go Live” part of enrollment.

NOTE:An Internet Merchant Account is different type of merchant account. It has additional

risks associated with card-not-present (e-commerce) transactions. It is different from a

merchant account used for face-to-face/card-present (in-person) retail transactions .

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.

About Credit Card Processing

Credit card processing occurs in 2 steps — a real-time authorization and a capture (settlement)

of the funds that the cardholder’s issuing bank authorizes. You perform these 2 steps either as

a single transaction or as 2 transactions, depending on your business model.

For an authorization, the server sends the transaction information to a credit card processor.

The processor routes the transaction through the financial networks to the cardholder’s issuing

bank. The issuing bank checks whether the card is valid. It evaluates whether sufficient credit

exists, checks values such as address verification service and card security codes, and returns a

response such as Approved, Declined, or Referral.

You receive the response a few seconds after you submit the transaction to the server. If the

bank approves an authorization, it 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 3-7 days.

Capturing a transaction actually transfers the funds to your bank. At least once a day, PayPal

gathers all transactions flagged for settlement and sends them in a batch file to the processor.

The processor then charges the issuing bank and transfers the funds to your bank. It typically

takes a few days before the money is available in your account, depending on your bank.

NOTE:For card-not-present transactions; such as online transactions, merchants are required

to provide a service or ship goods before or on the same day the transaction is

captured.

Credit Card Features

The Payflow SDK supports the following transaction types for credit card processing:

Transaction Type Billable

Authorization Yes

Account Verification No

Gateway Developer Guide and Reference 31 July 2012 49

Submitting Credit Card Transactions

Planning Your Gateway Integration 6

The Payflow SDK also supports the following credit card features:

-Address verification service and card security code validation

-Card-present (SWIPE) transactions

-Partial authorizations for pre-paid cards

-Purchasing card transactions

-Reference transactions (also called tokenization)

-Submitting Soft Merchant information

Planning Your Gateway Integration

When designing your Gateway integration, evaluate:

-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. Two-step: Perform 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.

According to card association rules, most physical goods merchants should use a two-step

process, since settlement should occur when the merchant ships the goods. A two-step

process is also useful for evaluating 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.

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

security code. For the address verification service, if the initial transaction submits the data,

Balance Inquiry No

Credit Yes

Delayed Capture No

Inquiry No

Sale Yes

Voice Authorization Yes

Vo i d Ye s

Transaction Type Billable

Submitting Credit Card Transactions

Planning Your Gateway Integration

50 31 July 2012 Gateway Developer Guide and Reference

the issuer checks the street address and the zip code against the billing address on file for

the consumer.

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

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.

-Whether to store information in your local database or use PayPal Manager reports to

manage the data. You may want to store shipping information in your system, or you may

prefer to send the information to PayPal with the transaction and report on it later.

NOTE:Consider whether and how to use COMMENT1 and COMMENT2 to help tie reports to

your orders/customers or to report on other information about the transaction.

-If or how you want to integrate with other systems, such as order fulfillment, Customer

Service, and so on. You may want to integrate your systems directly 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.

-Whether to discuss with your internet Merchant Acquirer practices that help you to obtain

the most advantageous rates.

Complying With E-commerce Indicator

Some processors support a software flag called E-commerce Indicator (ECI) that indicates that

the associated transaction is an internet transaction. The Payflow SDK complies with ECI

basic requirements for all supported processors.

If you use Buyer Authentication, the ECI values reflect the authentication status.

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 you do not accept, the SDK responds with RESULT value 25, “Invalid host

mapping,” or the processor returns a message that the customer is not signed up for the card

type. Optionally, you can provide your 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, contact your acquiring bank (holding your Internet

Merchant Account) and ask them to add the card type to your account. Upon notification from

your acquirer that you can start accepting the card type, add the card to your Payflow account

through PayPal Manager. See PayPal Manager online help for details.

Gateway Developer Guide and Reference 31 July 2012 51

Submitting Credit Card Transactions

Core Credit Card Parameters 6

NOTE:American Express cards require explicit acceptance when PayPal is the processor. To

accept American Express cards, go to the Profile Page in PayPal Manager and click

American Express card acceptance.

Core Credit Card Parameters

All credit card processors accept the basic parameters described in the following table with

one exception: the PayPal processor does not support SWIPE.

Parameter Description

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

-A = Automated clearinghouse (ACH)

-C = Credit card

-D = Pinless debit

-K = Telecheck

-P = PayPal

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

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

-A = Authorization

-B = Balance Inquiry

-C = Credit

-D = Delayed Capture

-F = Voice Authorization

-I = Inquiry

-L = Data Upload

-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 never settles.

-S = Sale

-V = Void

ACCT (Required for credit cards) Credit card or purchase card number. For example,

ACCT=5555555555554444. 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

EXPDATE (Required) Expiration date of the credit card. For example, 1215 represents

December 2015.

Limitations: mmyy format

Submitting Credit Card Transactions

Core Credit Card Parameters

52 31 July 2012 Gateway Developer Guide and Reference

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

Limitations: Specify the exact amount to the cent using a decimal point. For example,

use 34.00 not 34. Do not include comma separators. For example, use 1199.95 not

1,199.95. Your processor 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 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

RECURRING (Optional) Identifies the transaction as recurring. It is one of the following values:

-Y – Identifies the transaction as recurring.

-N – Does not identify the transaction as recurring (default).

This value does not activate the Payflow Recurring Billing Service API. If the

RECURRING parameter value is Y in the original transaction, this value is ignored

when forming credit, void, and force transactions. If you subscribe to the Payflow

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, follow the normal process to

review the filter results.

NOTE:If your transaction is declined and the PAYMENTADVICECODE response

parameter is supported by your processor, a PAYMENTADVICECODE value is

returned representing the reason that the transaction was declined. Obtain the

meaning of PAYMENTADVICECODE values from your acquiring bank.

Character length and limitations: 1 alpha character

SWIPE (Required for card-present transactions only) Used to pass the Track 1 or Track 2

data (card’s magnetic stripe information) for card-present transactions. Include either

Track 1 or Track 2 data—not both. If Track 1 is physically damaged, the point-of-sale

(POS) application can send Track 2 data instead.

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

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

Limitations: Alphanumeric and special characters

Parameter Description

Gateway Developer Guide and Reference 31 July 2012 53

Submitting Credit Card Transactions

Core Credit Card Parameters 6

ORDERID (Optional) Checks for a duplicate order. If you pass ORDERID in a request and pass it

again in the future, the response returns DUPLICATE=2 along with the ORDERID.

NOTE:Do not use ORDERID to catch duplicate orders processed within seconds of

each other. Use ORDERID with Request ID to prevent duplicates as a result of

processing or communication errors.

Character length and limitations: alphanumeric characters

BILLTOFIRSTNAME (Optional) Account holder's first name.

Limitations: 30 alphanumeric characters

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

Limitations: 30 alphanumeric characters

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

The address verification service verifies the STREET address.

Limitations: 150 alphanumeric characters

BILLTOCITY (Optional) Bill-to city.

Limitations: 45-character string.

BILLTOSTATE (Optional) Bill-to state.

Limitations: 45-character string.

Limitations: 10-character string.

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

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

characters

BILLTOCOUNTRY (Optional) Bill-to country.

Limitations: 3-character country code.

SHIPTOFIRSTNAME (Optional) Ship-to first name.

Limitations: 30-character string.

SHIPTOLASTNAME (Optional) Ship-to last name.

Limitations: 30-character string.

SHIPTOSTREET (Optional) Ship-to street address.

Limitations: 150-character string.

SHIPTOCITY (Optional) Ship-to city.

Limitations: 45-character string.

SHIPTOSTATE (Optional) Ship-to state.

Limitations: 45-character string.

Limitations: 10-character string.

SHIPTOZIP (Optional) Ship-to postal code.

Limitations: 10-character string.

Parameter Description

Submitting Credit Card Transactions

Submitting Account Verifications

54 31 July 2012 Gateway Developer Guide and Reference

Submitting Account Verifications

Account verification, also known as zero dollar authorization (TRXTYPE=A), verifies credit

card information. While you pass TRXTYPE=A for account verification and normal

authorization, account verification differs from authorization in the following ways:

-Always pass the AMT value 0. If you pass any other amount, the transaction becomes a

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

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

Verified rather than Approved.

NOTE:Payflow returns RESULT value 4, Invalid Amount, if the processor does not support

account verifications.

When To Use Account Verifications

Use 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 transaction. See

“Submitting Reference Transactions (Tokenization)” on page 66.

Required Account Verification Parameters

To perform account verification, pass the following parameters:

Example Account Verification String

The following is an example of account verification:

SHIPTOCOUNTRY (Optional) Ship-to country.

Limitations: 3-character country code.

Parameter Description

TRXTYPE (Required) Set to A.

Limitations: 1 alphanumeric character.

AMT (Required) Set to 0.

VERBOSITY (Required) Set to HIGH to obtain information about a partial authorization in the

response.

Parameter Description

Gateway Developer Guide and Reference 31 July 2012 55

Submitting Credit Card Transactions

Submitting Authorization/Delayed Capture Transactions 6

TRXTYPE=A&TENDER=C&PARTNER=PayPal&USER=SuperUser&PWD=SuperUserPasswo

rd&AMT=0.00&ACCT=378282246310005&EXPDATE=1215&INVNUM=PONUM1&VERBOSIT

Y=HIGH&BILLTOZIP=95031

This is the response:

RESULT=0&PNREF=VFHA0FF8F27D&RESPMSG=Verified&AUTHCODE=667PNI&AVSADDR

=X&AVSZIP=X&HOSTCODE=A&PROCAVS=U&AMEXID=123456789012345&AMEXPOSDATA=

123456789012&TRANSTIME=2011-01-

11 18:42:01&AMT=0.00&ACCT=0005&EXPDATE=1215&CARDTYPE=3&IAVS=X

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.

Perform a delayed capture (TRXTYPE=D) transaction after an authorization to capture the

original authorization amount. PayPal schedules the delayed capture for settlement during the

next settlement period.

Because Visa and MasterCard regulations prohibit capturing credit card payments until the

buyer receives the product or service, most processing networks implement an authorization

followed by a delayed capture.

NOTE:PayPal Payments Advanced and Payflow Link users cannot submit authorization

transactions unless they obtain the Payflow SDK.

When to Use Authorization/Delayed Capture Transactions

If your business does not provide immediate fulfillment of products or services, PayPal

recommends that you use delayed capture processing. It enables you to capture credit card

payments when you are ready to collect them.

NOTE:If you signed up for the PayPal processor with Fraud Protection Services, 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 69. To recharge a credit card when you are not storing

credit card information in your local database, perform a new reference transaction based on a

sale. For details, see “Submitting Reference Transactions (Tokenization)” on page 66.

NOTE:You are allowed to perform one delayed capture transaction per authorization

transaction.

Submitting Credit Card Transactions

Submitting Balance Inquiry Transactions

56 31 July 2012 Gateway Developer Guide and Reference

Required Authorization Transaction Parameters

To perform a delayed capture transaction, pass the following parameter:

Typical Authorization Transaction Parameter String

A typical NVP 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=SuperUser&PWD=SuperUserPassword&VENDOR=SuperUser&PA

RTNER=PayPal&ACCT=5105105105105100&EXPDATE=1215&CVV2=123&AMT=99.00&BILLTOFI

RSTNAME=John&BILLTOLASTNAME=Smith&BILLTOSTREET=123 Main St.&BILLTOCITY=San

Jose&BILLTOSTATE=CA&BILLTOZIP=12345&COMMENT1=Reservation&INVNUM=1234567890&

PONUM=C12345&VERBOSITY=HIGH

Submitting Balance Inquiry Transactions

Balance Inquiry (TRXTYPE=B) transactions are used to obtain the balance of a pre-paid card.

This transaction type is different from a balance inquiry performed during an authorization

transaction. However, both of these transaction types will return the balance in the BALAMT

response parameter.

NOTE:Payflow returns RESULT value 3, Invalid Transaction Type, if the processor does not

support balance inquiry.

Processing Platforms Supporting Balance Inquiry Transactions

The following processing platforms currently support pre-paid card balance inquiry

transactions. This feature will be added for more processors in the near future. As more

processors are added, this list will be updated accordingly.

Required Balance Inquiry Parameters

To perform a balance inquiry on a pre-paid card, pass the following parameters:

Parameter Description

ORIGID (Required by some transaction types) ID of the original transaction referenced.

The PNREF parameter returns this ID, and it appears as the Transaction ID in

PayPal Manager reports.

Limitations: 12 case-sensitive alphanumeric characters.

WorldPay

Gateway Developer Guide and Reference 31 July 2012 57

Submitting Credit Card Transactions

Submitting Card Present (SWIPE) Transactions 6

Example Balance Inquiry Transaction String

The following is an example of a balance inquiry transaction:

TRXTYPE=B&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperUser&PWD=S

uperUserPassword&ACCT=5555555555554444&EXPDATE=1215&VERBOSITY=HIGH

This is the response:

RESULT=0&PNREF=ERRV0A005933&RESPMSG=Approved&AUTHCODE=467PNI&HOSTCODE=000&T

RANSTIME=2012-02-

16 18:41:25&AMT=0.00&BALAMT=10.00&ACCT=4444&EXPDATE=1215&CARDTYPE=0

Submitting Card Present (SWIPE) Transactions

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

NOTE:The PayPal processor does not support SWIPE (card-present) transactions.

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

-Contact your merchant account provider to make sure that they support card-present

transactions.

-Contact PayPal Customer Service to request them to set up your account properly for

accepting and passing swipe data.

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

separate Gateway 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.

-A sale is the preferred method to use for card-present transactions. Consult with your

acquiring bank for recommendations on other methods.

Parameter Description

TRXTYPE (Required) Set to B.

Limitations: 1 alphanumeric character.

EXPDATE (Required) Expiration date of the pre-paid card in the format MMYY. For

example, 1215 represents December 2015.

VERBOSITY (Required) Set to HIGH to obtain information about a balance inquriy in the

response.

Submitting Credit Card Transactions

Submitting Card Present (SWIPE) Transactions

58 31 July 2012 Gateway Developer Guide and Reference

Processing Platforms Supporting Card-Present Transactions

The following processing platforms support card-present transactions.

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 (up to 80 alphanumeric characters). If

Track 1 is physically damaged, the POS application can send Track 2 data instead.

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 counts the

characters in the track data and passes that number as the length tag. For details on length tags,

see “Using Special Characters In Values” on page 43. The length tag in the following example

is [40].

American Express

American Express APAC

Elavon

Fifth Third Processing Solutions

First Data Merchant Services (FDMS) Nashville

First Data Merchant Services (FDMS) North

First Data Merchant Services (FDMS) South

Global Payments Central

Global Payments East

Heartland Payment Systems

Litle

Merchant e-Solutions

Moneris Solutions

Paymentech Salem

Paymentech Tampa

PayPal

SecureNet

TeleCheck

TSYS Acquiring Solutions

WorldPay

Gateway Developer Guide and Reference 31 July 2012 59

Submitting Credit Card Transactions

Submitting Credit Transactions 6

NOTE:Do not include the ACCT or EXPDATE parameters in card-present transactions. The

SWIPE value includes this data.

TRXTYPE=S&TENDER=C&PARTNER=PayPal&USER=SuperMerchant&PWD=SuperMerchant&SWIP

E[40]=;4912000033330026=15121011000012345678?&AMT=21.00

Submitting Credit Transactions

The credit transaction (TRXTYPE=C) refunds the specified amount back to the cardholder. A

credit transaction can contain a reference to the original transaction (referenced) or not (non-

referenced) depending on how your account is setup. To issue a credit, the original transaction

can only be one of the following: a Sale (TRXTYPE=S), Delayed Capture (TRXTYPE=D) or

Voice Authorization (TRXTYPE=F). It is recommended that the merchant issue a credit only if

the original transaction has already settled. Even though it is possible to issue a credit to a

transaction that has not settled, it is recommended that you void such transactions.

Both the credit transaction and the original transaction will appear on the customer’s

statement.

Required Credit Transaction Parameters

The required parameter data for a credit transaction depends on the Allow non-referenced

credits security setting for your Payflow account. A non-referenced credit is a credit

transaction that does not use the credit card information from an existing transaction. You

provide the credit card information. As an example, Sally Smith calls you on the phone 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

non-referenced credits are allowed.

Non-Referenced Credits Not Allowed

When non-referenced credits are not allowed (the setting recommended by PayPal), credit

transactions are permitted only against existing sale, delayed capture, and voice authorization

transactions. To submit a credit transaction when non-referenced credits are not allowed, pass

the following parameter:

Parameter Description

ORIGID (Required by some transaction types) ID of the original transaction referenced.

The PNREF parameter returns this ID, and it appears as the Transaction ID in

PayPal Manager reports.

Limitations: 12 case-sensitive alphanumeric characters.

Submitting Credit Card Transactions

Submitting Credit Transactions

60 31 July 2012 Gateway Developer Guide and Reference

Set the value of ORIGID to the PNREF value returned for the original transaction. (PayPal

Manager reports display the PNREF as the Transaction ID.) If you do not specify an amount,

the amount of the original transaction is credited to the cardholder.

Non-Referenced Credits Allowed

When non-referenced credits are allowed, 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:

-ACCT

-EXPDATE

-AMT

NOTE:The default security setting for Gateway accounts is Allow non-referenced credits =

No. Sending the ORIGID is the preferred method for performing credit transactions.

Using the ACCT, EXPDATE, or AMT parameters for such accounts leads to the return of

RESULT value 117 (failed the security check). To help reduce fraud, PayPal

recommends that you not activate non-referenced credits unless you have a business

reason. For information on setting the security settings, see PayPal Manager online

help.

Set the value of ORIGID to the PNREF value returned for the original transaction. (PayPal

Manager reports display the PNREF as the Transaction ID.) If you do not specify an amount,

then the amount of the original transaction is credited to the cardholder.

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, 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 you set the RECURRING

parameter to Y in the original transaction, this setting is ignored when forming the

credit transaction.

Parameter Description

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

referenced. The PNREF parameter returns this ID, and it appears as the

Transaction ID in PayPal Manager reports.

Limitations: 12 case-sensitive alphanumeric characters

Gateway Developer Guide and Reference 31 July 2012 61

Submitting Credit Card Transactions

Submitting Inquiry Transactions 6

Example Credit Transaction Parameter Strings

The following is an example of a credit transaction string (non-referenced credits not

allowed):

TRXTYPE=C&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant&P

WD=x1y2z3&ORIGID=VPNE12564395

The following is an example credit transaction string (non-referenced credits allowed):

TRXTYPE=C&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant&P

WD=x1y2z3&ACCT=5555555555554444&EXPDATE=1215&AMT=123.00&VERBOSITY=HIGH

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. You can also perform an inquiry using the secure token.

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

closely as possible.

Required Parameters When Using the PNREF

To perform an inquiry, pass the following parameter:

ACCT AMT BILLTOCITY BILLTOCOUNTRY

BILLTOEMAIL BILLTOMIDDLENAME BILLTOLASTNAME BILLTOPHONENUM

BILLTOSTATE BILLTOSTREET BILLTOZIP COMMENT1

COMMENT2 COMPANYNAME CUSTCODE CUSTIP

EXPDATE INVNUM PONUM SHIPTOCITY

SHIPTOCOUNTRY SHIPTOFIRSTNAME SHIPTOMIDDLENAME SHIPTOLASTNAME

SHIPTOSTATE SHIPTOSTREET SHIPTOZIP SWIPE

Submitting Credit Card Transactions

Submitting Inquiry Transactions

62 31 July 2012 Gateway Developer Guide and Reference

Set ORIGID to the PNREF (Transaction ID in PayPal Manager reports) value returned in the

original transaction.

Inquiry Transaction Parameter String 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=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant&P

WD=x1y2z3&ORIGID=VPNE12564395&VERBOSITY=HIGH

Required Parameters When Using the CUSTREF

To perform an inquiry transaction when using the CUSTREF, pass the CUSTREF parameter.

Parameter Description

ORIGID (Required by some transaction types) ID of the original transaction referenced.

The PNREF parameter returns this ID, and it appears as the Transaction ID in

PayPal Manager reports.

Limitations: 12 case-sensitive alphanumeric characters.

Parameter Description

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

example, you can set CUSTREF to the invoice number.

You can use CUSTREF when performing inquiry transactions. To make sure that

you can always access the correct transaction when performing an inquiry,

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.

STARTTIME specifies the beginning of the time period during which the

transaction specified by the CUSTREF occurred.

ENDTIME must be less than 30 days after STARTTIME. You cannot perform an

inquiry across a date range greater than 30 days.

If you set ENDTIME, and not STARTTIME, STARTTIME defaults to 30 days

before ENDTIME.

If you do not specify a STARTTIME or ENDTIME, the system searches the last 30

days.

Limitations: 14 numeric characters in the format yyyymmddhhmmss

Gateway Developer Guide and Reference 31 July 2012 63

Submitting Credit Card Transactions

Submitting Inquiry Transactions 6

NOTE:If there are multiple transactions with a particular CUSTREF value, inquiry returns the

last transaction only with the specified CUSTREF. To make sure that you can always

access the correct transaction, use a unique CUSTREF when submitting any

transaction, including retries.

Inquiry Transaction Parameter String Using the CUSTREF

This is an example inquiry parameter string using the CUSTREF.

TRXTYPE=I&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant

&PWD=x1y2z3&CUSTREF=Inv00012345

Required Parameters When Using the Secure Token

To perform an inquiry transaction when using the secure token, pass the following parameter:

Set SECURETOKEN to the PNREF (Transaction ID in PayPal Manager reports) value returned

for the original transaction.

Inquiry Parameter String Using the Secure Token

The following is an example inquiry request string with the SECURETOKEN parameter.

TRXTYPE=I&TENDER=C&PARTNER=PayPal&PWD=SuperUserPassword&USER=SuperMerchant&

VERBOSITY=HIGH&VENDOR=SuperMerchant&SECURETOKEN=FmyM1y7wy8kiS6aumnMPhTQN&VE

RBOSITY=HIGH

The following is the response string.

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.

Limitations: 14 numeric characters

Parameter Description

SECURETOKEN (Required) A value the Payflow server created upon your request for storing

transaction data.

Limitations: 32 alphanumeric characters

Parameter Description

Submitting Credit Card Transactions

Submitting Partial Authorizations

64 31 July 2012 Gateway Developer Guide and Reference

RESULT=0&PNREF=VFHE1A0CB0A9&TRANSSTATE=6&ORIGRESULT=0&ORIGPNREF=VFHE1A0CB0A

8&RESPMSG=Approved&AUTHCODE=010101&AVSADDR=Y&AVSZIP=Y&HOSTCODE=00&PROCAVS=Y

&DATE_TO_SETTLE=2011-02-04 16:16:50&TRANSTIME=2011-02-

04 16:16:50&BILLTOFIRSTNAME=James&BILLTOLASTNAME=Smith&AMT=555.00&ACCT=0002

&EXPDATE=0120&CARDTYPE=0&IAVS=N

Submitting Partial Authorizations

A partial authorization is a partial approval of an authorization (TRXTYPE=A) transaction. A

partial authorization approves a transaction when the balance available is less than the amount

of the transaction. The transaction response returns the amount of the original transaction and

the amount approved.

When To Use Partial Authorizations

Use partial authorizations to reduce the number of declines resulting from buyers spending

more than their balance on prepaid cards.

Say, for example, that you sell sportswear on your website. Joe purchases a pair of running

shoes in the amount of $100.00. At checkout, Joe uses a giftcard with a balance of $80.00 to

pay. You request partial authorization of $100.00. The transaction response returns the original

amount of $100.00 and the approved amount of $80.00.

You can take either of the following actions:

-Accept the $80.00 and ask the buyer to provide an alternate payment for the additional

$20.00.

-Reject the partial authorization and submit to the card issuer an authorization reversal

(Void) for $80.00.

Required Partial Authorization Parameters

To perform a partial authorization, pass the same parameters that you would for an

authorization (TRXTYPE=A, ACCT, AMT, and EXPDATE). In addition, pass the following

parameters.

Parameter Description

PARTIALAUTH (Required) Set to Y to submit a partial authorization.

Limitations: 1 alphanumeric character.

VERBOSITY (Required) Set to HIGH to obtain information about a partial authorization in the

response.

Gateway Developer Guide and Reference 31 July 2012 65

Submitting Credit Card Transactions

Submitting Purchasing Card Transactions 6

Example Partial Authorization

The following is an example partial authorization.

1. You submit the initial authorization as a partial authorization.

TRXTYPE=A&TENDER=C&AMT=100.00&ACCT=4111111111111111&EXPDATE=0119

&PARTIALAUTH=Y&VERBOSITY=HIGH

2. The card issuer notes that the card has a remaining balance of $80.00.

3. The card issuer sends a partial authorization for $80.00.

RESULT=0&PNREF=VRNS1A3B33C9&RESPMSG=Partial

Approval&AUTHCODE=11111&HOSTCODE=E&PROCAVS=U&TRANSTIME=2010-04-21

11:30:45&AMT=80.00&ORIGAMT=100.00&BALAMT=0&ACCT=1111&EXPDATE=0119&IAVS=X

RESPMSG is Partial Approval, AMT is now the actual amount approved, ORIGAMT is

the original requested amount, and BALAMT is the balance on the card.

Since the amount charged is greater than the amount available on the card, the response

sets the balance amount (BALAMT) to zero. If BALAMT is zero, check if there is a balance

due by comparing the original amount to the amount charged (ORIGAMT-AMT).

4. You can choose to perform one of the following tasks:

– Accept the $80.00 and request an alternate payment from the buyer for the additional

$20.00.

– Reject the partial authorization by sending the card issuer an authorization reversal

(void) for $80.

Submitting Purchasing Card Transactions

A purchasing card (also referred to as a commercial card, corporate card, procurement card or

business card) is a credit card that an employer requests to be issued. A purchasing card 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, pass specific additional

transaction information. Purchasing card support and parameters vary from processor to

processor. See “Submitting Purchasing Card Level 2 and Level 3 Transactions” on page 143.

NOTE:The PayPal processor does not support purchasing card transactions.

Submitting Credit Card Transactions

Submitting Reference Transactions (Tokenization)

66 31 July 2012 Gateway Developer Guide and Reference

Submitting Reference Transactions (Tokenization)

To recharge a credit card when 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. (Securely storing data for future reference

is also known as tokenization.)

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

months. You can also use the PNREF account verification returns in a reference transaction.

When To Use a Reference Transaction

Say that Joe Smith purchases a holiday gift from your website store and requests that you send

it by UPS ground service. That evening, Joe becomes concerned that the item might not arrive

in time for the holiday. So Joe calls you to upgrade shipping to second-day air. You obtain

Joe’s approval for charging an extra $10 for the upgrade. 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 credit card information.

NOTE: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 that does not allow reference

transactions, Payflow returns RESULT value 117. See PayPal Manager online help for

instructions on setting reference transactions and other security features.

Sale and authorization transactions can use a reference transaction as a source of transaction

data. Payflow looks up the reference transaction and copies its transaction data into the new

sale or authorization. Except for dollar amount data, which triggers a filter if out of range,

Fraud Protection Service filters do not screen reference transactions.

NOTE:When the Gateway looks up the reference transaction, it does not alter in any way the

transaction referenced or any other transaction in the database. A reference transaction

is a read-only operation. Payflow populates with data and acts upon the new

transaction only. It does not maintain any linkage between the reference transaction

and the new transaction.

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

help for details.

Transaction Types That Can Be Used As the Original Transaction

You can reference the following transaction types to supply data for a new sale or

authorization transaction:

-Authorization (To capture the funds for an approved authorization transaction, be sure to

perform a delayed capture transaction—not a reference transaction.)

-Credit

Gateway Developer Guide and Reference 31 July 2012 67

Submitting Credit Card Transactions

Submitting Reference Transactions (Tokenization) 6

-Delayed capture

-Sale

-Voice authorization (Payflow does not copy the voice authorization code to the new

transaction)

-Vo i d

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.

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. You charge the $34 for the final part of the

shipment using a reference transaction to draw credit card and shipping address information

from the initial authorization transaction.

This example procedure creates a reference transaction:

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

You use an authorization transaction for the full amount of the purchase of $100 as shown

in this transaction request:

TRXTYPE=A&TENDER=C&PWD=x1y2z3&PARTNER=PayPal&VENDOR=SuperMerchant&USER=Supe

rMerchant&ACCT=5555555555554444&EXPDATE=1215&AMT=100.00&INVNUM=123456789&BI

LLTOSTREET=5199 MAPLE&BILLTOZIP=94588

Note the value of the PNREF in the response:

RESULT=0&PNREF=VXYZ01234567&RESPMSG=APPROVED&AUTHCODE=123456&AVSADDR=Y&AVSZ

IP=N

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

12 months.

ACCTTYPE BILLTOSTREET

ACCT BILLTOCITY

EXPDATE BILLTOSTATE

BILLTOFIRSTNAME BILLTOZIP

BILLTOMIDDLENAME BILLTOCOUNTRY

BILLTOLASTNAME SWIPE

Submitting Credit Card Transactions

Submitting Reference Transactions (Tokenization)

68 31 July 2012 Gateway Developer Guide and Reference

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.

TRXTYPE=D&TENDER=C&PWD=x1y2z3&PARTNER=PayPal&VENDOR=SuperMerchant&USER=Supe

rMerchant&ORIGID=VXYZ01234567&AMT=66.00

The following is the response:

RESULT=0&PNREF=VXYZ01234568&AUTHCODE=25TEST&AVSADDR=Y&AVSZIP=N

3. Submit a new sale transaction or an authorization and delayed capture transaction of $34

for the rest of the shipment.

When you ship 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 Payflow allows only one delayed capture transaction per

authorization.)

The following is a sale transaction request:

TRXTYPE=S&TENDER=C&PWD=x1y2z3&PARTNER=PayPal&VENDOR=SuperMerchant&USER=Supe

rMerchant&ORIGID=VXYZ01234567&AMT=34.00

The following is the response:

RESULT=0&PNREF=VXYZ01234569&AUTHCODE=25TEST&AVSADDR=Y&AVSZIP=N

Data Upload - Storing Credit Card Data on the Gateway Server

To facilitate creating reference transactions while assisting you with PCI compliance, PayPal

allows you to upload credit card data by submitting an upload transaction (TRXTYPE=L). At

minimum, you must pass values for the following parameters:

-TRXTYPE

-TENDER

-ACCT

-EXPDATE

This is an example upload transaction request:

TRXTYPE=L&TENDER=C&ACCT=5105105105105100&EXPDATE=1215&BILLTOFIRSTNAME=Ted&B

ILLTOLASTNAME=Smith&BILLTOSTREET=123&BILLTOCITY=SanJose&BILLTOSTATE=CA&BILL

TOZIP=12345&BILLTOPHONENUM=123-123-1234

This is the response:

RESULT=0&PNREF=v19A2E710FCF&RESPMSG=Approved&TRANSTIME=2011-11-02 16:53:58

Gateway Developer Guide and Reference 31 July 2012 69

Submitting Credit Card Transactions

Submitting Sale Transactions 6

You can send shipping and billing information to be stored, but you must not include the AMT

field. If you pass a value for AMT, you will receive an error with RESULT=4 and

RESPMSG=Invalid Amount.

NOTE:PayPal does not verify the credit card data, as it is not sent to the banks for processing.

To validate a transaction, you must submit an account verification, also known as a

zero dollar authorization (TRXTYPE=A). For details, see “Submitting Account

Verifications” on page 54.

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.

NOTE:PayPal Payments Advanced and Payflow Link users cannot submit sale transactions

unless they obtain the Payflow SDK.

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, 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 55. To

recharge a credit card when 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, pass the following parameters:

-ACCT

-AMT

-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, pass values for the

ACCT and AMT parameters. The First Data Merchant Services (FDMS) South

processing platform supports sale and credit transactions only.

Typical Sale Transaction Parameter String

The following is a typical NVP string passed in a sale transaction.

Submitting Credit Card Transactions

Submitting Soft Merchant Information

70 31 July 2012 Gateway Developer Guide and Reference

TRXTYPE=S&TENDER=C&USER=SuperUser&PWD=SuperUserPassword&VENDOR=SuperUser&PA

RTNER=PayPal&ACCT=5105105105105100&EXPDATE=1215&CVV2=123&AMT=99.00&BILLTOFI

RSTNAME=John&BILLTOLASTNAME=Smith&BILLTOSTREET=123 Main St.&BILLTOCITY=San

Jose&BILLTOSTATE=CA&BILLTOZIP=12345&COMMENT1=Reservation&INVNUM=1234567890&

PONUM=C12345&VERBOSITY=HIGH

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. Pass the customer’s street address (BILLTOSTREET) and zip code (BILLTOZIP)

to use address verification service. To validate card security codes, pass the CVV2 parameter.

For details on address verification service and card security code, see the following:

-“Submitting Card Present (SWIPE) Transactions” on page 57

-“Using Card Security Code” on page 75

Submitting Soft Merchant Information

Soft merchant information is detailed data about a merchant such as the merchant’s name,

business address, business location identifier, and contact information.

About Soft Merchant Information

Merchants aggregators, who perform transactions on behalf of other merchants under a single

merchant account, provide the processor with soft merchant information. Soft merchant

information identifies the merchant making the sale and includes information about that

merchant on the buyer’s card statement.

Say, for example, Outdoor Apparel has a chain of 12 stores located in the Western United

States with the corporate office in Oakland, California. John Lui purchases a pair of hiking

boots online from Hiker’s Duds in San Jose, California, and charges them to his credit card.

The transaction goes to the aggregator at Outdoor Apparel in Oakland. The aggregator sends

soft merchant information about the Hiker’s Duds store with the transaction to the credit card

processor. When John receives his credit card statement, he recognizes the charge for the

hiking boots he purchased at Hiker’s Duds in San Jose.

Ways to Send Soft Merchant Information

There are 2 ways you can send soft merchant information:

-Soft merchant information (SM Record)

-Merchant descriptor (M Record)

The Paymentech processor requires that you follow their guidelines to send soft descriptor

information using either of these methods.

Gateway Developer Guide and Reference 31 July 2012 71

Submitting Credit Card Transactions

Submitting Voice Authorization Transactions 6

Soft Merchant Information (SM Record)

Soft merchant information is for American Express credit cards only. Typically aggregators

(and petroleum merchants) pass soft merchant information to the processor in Gateway

parameter fields such as the following:

-MERCHANTNAME

-MERCHANTSTREET

-MERCHANTCITY

-MERCHANTSTATE

-MERCHANTNAME

-MERCHANTZIP

-MERCHANTCOUNTRYCODE

-MERCHANTLOCATIONID

-MERCHANTID

-MERCHANTCONTACTINFO

NOTE:Paymentech Salem processor only: To take advantage of this level of soft descriptor,

you must be approved by the Paymentech Risk/Credit department. Upon approval,

Paymentech sets a flag at the transaction division to enable you to send the preceding

parameters. If the flag is not set and you send the parameters, your transaction is

rejected with Error 258.

Merchant Descriptor (M Record)

A merchant descriptor defines the merchant name and product that appears on the account

holder’s statement. The descriptior information is passed to the processor in parameter fields

such as the following:

-MERCHDESCR – Defines the merchant name and product

-MERCHSVC – Includes the merchant contact information such as the merchant’s telephone

number, e-mail address, or website URL

To use merchant descriptors, you are not required to have the processor set the division level

flag. However, you are required to obtain prior risk or credit department approval before

sending the parameters.

Submitting Voice Authorization Transactions

A voice authorization (TRXTYPE=F) is a transaction that the processing network authorizes

over the phone.

NOTE:The PayPal processor does not support voice authorization transactions.

Submitting Credit Card Transactions

Submitting Void Transactions

72 31 July 2012 Gateway Developer Guide and Reference

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 referral transactions generate RESULT value 13.

In these situations, you contact the customer service department of your merchant bank and

provide the payment information as requested. If the bank approves the transaction, the bank

provides you with a voice authorization code (AUTHCODE) for the transaction..

On approval, a voice authorization transaction is treated like a sale transaction and is settled

with no further action on your part.

Like sale transactions, you can void approved voice authorizations before settlement occurs.

Required Voice Authorization Transaction Parameters

To perform a voice authorization transaction, pass the AUTHCODE provided by your merchant

bank.

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

TRXTYPE=F&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant&P

WD=x1y2z3&AUTHCODE=AB3456&ACCT=5555555555554444&EXPDATE=1215&AMT=123.00&VER

BOSITY=HIGH

Submitting Void Transactions

The void transaction (TRXTYPE=V) prevents authorizations from being captured, and delayed

captures, sales and voice authorizations from being settled.

You cannot void another void transaction or any inquiry type transactions. The void

transaction and the original transaction will not appear on the customer’s statement.

PayPal will issue an authorization reversal as part of the void transaction for debit and credit

cards if the processor supports it. Because the bank or issuer ultimately decides whether to

honor authorization reversals, there is no accurate way to determine if an authorization

reversal was completed and the hold on funds has been removed.

Parameter Description

AUTHCODE (Required for voice authorizations) Returned only for approved voice

authorization transactions. AUTHCODE is the approval code received over the

phone from the processing network.

Limitations: 6 alphanumeric characters

Gateway Developer Guide and Reference 31 July 2012 73

Submitting Credit Card Transactions

Submitting Void Transactions 6

When To Use a Void Transaction

Use the following guidelines when using void transactions:

-You can void delayed capture, sale, credit, authorization, and voice authorization

transactions. You cannot void a void transaction.

-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, submit a credit transaction.

Required Void Transaction Parameters

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

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, 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 you set the RECURRING

parameter to Y in the original transaction, the setting is ignored when forming the void

transaction.

Parameter Description

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

referenced. The PNREF parameter returns the ID, and it appears as the

Transaction ID in PayPal Manager reports.

Limitations: 12 case-sensitive alphanumeric characters

ACCT AMT BILLTOCITY COMMENT1

COMMENT2 COMPANYNAME BILLTOCOUNTRY CUSTCODE

CUSTIP DUTYAMT BILLTOEMAIL EXPDATE

BILLTOFIRSTNAME BILLTOMIDDLENAME BILLTOLASTNAME FREIGHTAMT

INVNUM PONUM SHIPTOCITY SHIPTOCOUNTRY

SHIPTOFIRSTNAME SHIPTOMIDDLENAME SHIPTOLASTNAME SHIPTOSTATE

SHIPTOSTREET SHIPTOZIP BILLTOSTATE BILLTOSTREET

SWIPE TAXAMT BILLTOPHONENUM TAXEXEMPT

BILLTOZIP

Submitting Credit Card Transactions

Using Address Verification Service

74 31 July 2012 Gateway Developer Guide and Reference

Example Void Transaction Parameter String

The following is an example void transaction string:

TRXTYPE=V&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant&P

WD=x1y2z3&ORIGID=VPNE12564395&VERBOSITY=HIGH

Using Address Verification Service

To qualify for the lowest bank rate, pass address verification service information, including the

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 decides to approve or decline a

transaction. Most US banks and some international banks support the address verification

service.

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 the address

verification service response is international (Y), USA (N), or cannot be determined (X).

NOTE:When you set VERBOSITY to HIGH, the Gateway returns the processor’s raw response

in the PROCAVS field. To obtain details about the meaning of the response, contact

your merchant bank.

Example Address Verification Service Parameter String

This example request includes the address verification service parameters BILLTOSTREET

and BILLTOZIP:

TRXTYPE=A&TENDER=C&PWD=SuperUserPassword&PARTNER=PayPal&VENDOR=Vendor&USER=

SuperMerchant&&ACCT=5555555555554444&EXPDATE=1215&AMT=123.00&BILLTOSTREET=5

199 Maple&BILLTOZIP=98765

In this example response, 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&RESPMSG=APPROVED&AUTHCODE=123456&AVSADDR=Y&AVSZ

IP=N&IAVS=X

Gateway Developer Guide and Reference 31 July 2012 75

Submitting Credit Card Transactions

Using Card Security Code 6

Using Card Security Code

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 code provides some assurance that the physical card is in the

buyer’s possession.

This fraud prevention tool has various names, depending on the payment network. Visa calls it

CVV2, MasterCard calls it CVC2 while American Express and Discover call it CID. To make

sure that your customers see a consistent name, PayPal recommends use of the term card

security code on all end-user materials.

On most cards (Diners Club, Discover, Mastercard and Visa) the card security code is a 3-digit

number 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). American Express prints a

4-digit number (1122 in the example) on the front of the card, above and to the right of the

embossed account number. Make sure that you explain this to your customers.

To validate the card security code in a transaction, pass the card security code value in the

CVV2 parameter in your request. The response parameter CVV2MATCH returns the result of the

card security code check.

NOTE:To comply with credit card association regulations, do not store the card security code

value that you pass in the CVV2 parameter.

Card security code

The following is an example request parameter string.

TRXTYPE=S&TENDER=C&USER=SuperUser&PWD=SuperUserPassword&VENDOR=SuperUser&PA

RTNER=PayPal&ACCT=5105105105105100&EXPDATE=1215&CVV2=123&AMT=99.00&BILLTOFI

RSTNAME=John&BILLTOLASTNAME=Smith&BILLTOSTREET=123 Main St.&BILLTOCITY=San

Jose&BILLTOSTATE=CA&BILLTOZIP=12345

NOTE:Payflow returns the raw response from the processor in the PROCCVV2 parameter. For

details on the meaning of the response, contact your merchant bank.

Submitting Credit Card Transactions

Using Card Security Code

76 31 July 2012 Gateway Developer Guide and Reference

Gateway Developer Guide and Reference 31 July 2012 77

7Testing Transactions

Before you activate your website or application for use by buyers, test your integration. A

simulated payment network handles transactions, enabling you to verify the configuration and

operation of your website or application. No money changes hands.

Setting Up The Payflow Gateway Testing Environment

Before testing transactions be sure you are linked to the test servers.

Direct all transactions to the host URL for testing. See “Host URL Addresses” on page 42.

PayPal’s simulated network processes transactions directed to the URL.

Testing Guidelines

Follow these guidelines for testing.

-While testing, use only the credit card numbers for testing. Other numbers produce an

error.

-Expiration date must be a valid date in the future. Use the format mmyy.

-To view the credit card processor that you have selected for testing, see PayPal Manager.

Processors Other Than PayPal

For processors other than the PayPal processor, use the guidelines below.

Credit Card Numbers for Testing

For processors other than PayPal, use the following credit card numbers for testing. Any other

card number produces a general failure.

American Express 378282246310005

American Express 371449635398431

American Express Corporate 378734493671000

Testing Transactions

Processors Other Than PayPal

78 31 July 2012 Gateway Developer Guide and Reference

Result Values Based On Amount Submitted

You can use the amount of the transaction to generate a particular result value. The following

table lists the general guidelines for specifying amounts to submit in requests.

Result Values Based On Amount Submitted and Processor

This table lists the RESULT values that you can generate using the amount of the transaction.

To generate a specific value, submit an amount of 1000 plus the RESULT value number (for

example, submit an amount of 1013 for a RESULT value of 13).

Diners Club 38520000023237

Discover 6011111111111117

Discover 6011000990139424

JCB 3530111333300000

JCB 3566002020360505

MasterCard 5555555555554444

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.

Amount Result

$0 – $1000 RESULT value 0 (Approved)

$1001 – $2000 Certain amounts in this range return specific PayPal results. You can generate

the results 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 result supported by

this testing mechanism, Payflow returns RESULT value 12 (Declined).

$2001+ RESULT value 12 (Declined)

Processing Platform RESULT Values Available for Testing

American Express Brighton 0, 12, 13, 104, 1000

Elavon 0, 12, 13, 104

Gateway Developer Guide and Reference 31 July 2012 79

Testing Transactions

Processors Other Than PayPal 7

Result Values Based On Alternate Generation Methods

The following table shows another method for obtaining RESULT values. Servers do not return

non-zero RESULT values from processors. Therefore, you cannot simulate non-zero RESULT

values using the amount. In some cases, you may obtain certain results using the RESULT

value plus 1000 even though this table suggests an alternate means of obtaining the RESULT

value.

First Data Merchant Services North 0, 4, 5, 12, 13, 23, 24,114, 1000

First Data Merchant Services Nashville 0, 12, 13, 104

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 0, 4, 12, 13, 23, 104, 114, 1000

Vantiv (formerly Fifth Third Processing Solutions) 0, 4, 5, 12, 13, 23, 24,114, 1000

RESULT value Definition How to test using Payflow Gateway

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 Use the AMOUNT 1005 - Applies only to the following

processors: Global Payments East and Central, and

American Express

7 Field format error Submit a delayed capture transaction with no ORIGID

12 Declined Use the AMOUNT 1012 or an AMOUNT of 2001 or

13 Referral Use the AMOUNT 1013

Processing Platform RESULT Values Available for Testing

Testing Transactions

Processors Other Than PayPal

80 31 July 2012 Gateway Developer Guide and Reference

19 Original transaction ID not

found

Submit a delayed capture transaction with an invalid

ORIGID

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 Submit 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 Global Payments Central

processors

50 Insufficient funds available Use the AMOUNT 1050 - Only applies to Paymentech

99 General error Use the AMOUNT 1099 - Only applies to Global

Payments East

100 Invalid transaction returned

from host (Processor)

Use the AMOUNT 1100 - Only applies to Global

Payments East and Central

101 Time-out value too small Set timeout value to 1

103 Error reading response from

host (Processor)

Use the AMOUNT 1103

104 Timeout waiting for processor

response

Use the AMOUNT 1104

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

submitting an amount of 1112, but must submit a

value for Address Verification Service that 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

RESULT value Definition How to test using Payflow Gateway

Gateway Developer Guide and Reference 31 July 2012 81

Testing Transactions

Processors Other Than PayPal 7

Testing Address Verification Service

The Payflow testing server simulates address verification service by returning a value for

AVSADDR based on the first 3 characters of the submitted value for BILLTOSTREET.

The testing server returns a value for AVSZIP based on the submitted BILLTOZIP value as

shown in the table.

If BILLTOSTREET starts with 667 or higher or begins with a non-numeric character, then the

simulator returns AVSADDR=X, AVSZIP=X.

The following table tests AVSADDR.

The following table tests AVSZIP.

114 CVV2 Mismatch Use the AMOUNT 1114. Only applies to TSYS

Acquiring Solutions, Merchant e-Solutions, and

Global Payments East and Global Payments Central

processors

1000 Generic Host (Processor) Error Use the AMOUNT 2000 - Does not apply to Elavon

(formerly Nova), American Express, or Global

Payments East processors

Submitted Value for

BILLTOSTREET

Example BILLTOSTREET

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

Submitted Value for BILLTOZIP Example BILLTOZIP 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)

BILLTOSTREET=79232 Maple,

BILLTOZIP=20304

RESULT value Definition How to test using Payflow Gateway

Testing Transactions

PayPal Processor

82 31 July 2012 Gateway Developer Guide and Reference

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

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.

For the testing server, the first three characters of the CVV2 value determine the CVV2MATCH

result, as shown here.

Testing CVV2MATCH

PayPal Processor

For the PayPal processor, use the following guidelines.

Credit Card Numbers for Testing

For the PayPal processor, use the following credit card numbers for testing. Any other card

number produces a general failure.

CVV2 Value CVV2MATCH Value

000 Y

001-300 Y

301-600 N

601 or higher X

American Express 378282246310005

American Express 371449635398431

Amex Corporate 378734493671000

Australian BankCard 5610591081018250

Diners Club 30569309025904

Diners Club 38520000023237

Discover 6011111111111117

Discover 6011000990139424

Gateway Developer Guide and Reference 31 July 2012 83

Testing Transactions

PayPal Processor 7

Result Values Based On Amount

The following table shows another method for obtaining RESULT values. The servers do not

return non-zero RESULT values from processors.Therefore you cannot simulate non-zero

RESULT values using the amount. In some cases, you may obtain certain results using the

RESULT value plus 1000 even though this table suggests another means of obtaining the

RESULT value.

JCB 3530111333300000

JCB 3566002020360505

MasterCard 5555555555554444

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 Definition How to test

0 Approved Use an AMOUNT of 10000 or less

3 Invalid transaction type Use the AMOUNT 10402

4 Invalid amount Use any of these as AMOUNT:

-10400

-10401

-10403

-10404

5 Invalid merchant information Use any of these as AMOUNT:

-10548

-10549

Testing Transactions

PayPal Processor

84 31 July 2012 Gateway Developer Guide and Reference

7 Field format error Use any of these as AMOUNT:

-10405

-10406

-10407

-10408

-10409

-10410

-10412

-10413

-10416

-10419

-10420

-10421

-10509

-10512

-10513

-10514

-10515

-10516

-10517

-10518

-10540

-10542

12 Declined Use any of these as AMOUNT:

-10417

-15002

-15005

-15006

-15028

-15039

-10544

-10545

-10546

13 Referral Use the AMOUNT 10422

23 Invalid account number Use any of these as AMOUNT:

-10519

-10521

-10522

-10527

-10535

-10541

-10543

Result Definition How to test

Gateway Developer Guide and Reference 31 July 2012 85

Testing Transactions

PayPal Processor 7

24 Invalid expiration date Use any of these as AMOUNT:

-10502

-10508

30 Duplicate Transaction Use the AMOUNT 10536

105 Credit error Attempt to credit an authorization

112 Failed AVS check Use the AMOUNT 10505

114 CVV2 Mismatch Use the AMOUNT 10504

1000 Generic Host (Processor) Error Use an AMOUNT other than those listed in this column

Result Definition How to test

Testing Transactions

PayPal Processor

86 31 July 2012 Gateway Developer Guide and Reference

Gateway Developer Guide and Reference 31 July 2012 87

8Transaction Responses

When a transaction finishes, the Payflow server returns a response string made up of name-

value pairs. The following is an example response string:

RESULT=0&PNREF=EFHP0D426A53&RESPMSG=APPROVED&AUTHCODE=25TEST&AVSADDR=Y&AVSZ

IP=N&CVV2MATCH=Y

Credit Card Transaction Responses

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

Field Description

PNREF Gateway 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.

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

string when RESULT=0. For more information on corrective actions, see the

PayPal developer documentation on the PayPal developer website.

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)

Transaction Responses

Credit Card Transaction Responses

88 31 July 2012 Gateway Developer Guide and Reference

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.

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

string when RESULT=0. For more information on corrective actions, see the

PayPal developer documentation on the PayPal developer website.

NOTE:For partial authorizations, RESPMSG=Partial Approval when

RESULT=0.

Character length and limitations: variable, alphanumeric characters

AUTHCODE Returned for sale, authorization, and voice authorization credit card transactions.

AUTHCODE is the approval code obtained over the telephone from the processing

network.

AUTHCODE is required when submitting a force (F) transaction.

Character length and limitations: 6 alphanumeric characters

AVSADDR Address verification service address response returned if you are using address

verification service. Address verification service address responses are for advice

only. This process does not affect the outcome of the authorization.

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

AVSZIP Address verification service address response returned if you are using address

verification service. Address verification service address responses are for advice

only. This process does not affect the outcome of the authorization.

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

IAVS International address 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 The raw address verification service response returned by the processor. This field is

not normalized and is returned when VERBOSITY is set to HIGH.

Character length and limitations: 1 character

PROCCVV2 The raw CVV2 response returned by the processor. This field is not normalized and is

returned when VERBOSITY is set to HIGH.

Character length and limitations: 1 character

Field Description

Gateway Developer Guide and Reference 31 July 2012 89

Transaction Responses

Credit Card Transaction Responses 8

HOSTCODE The raw response code returned by the processor. This field is not normalized and is

returned when VERBOSITY is set to HIGH. Use RESPTEXT to obtain the response

message from the processor. For additional PayPal processor response code

information, refer to the PayPal API error codes. For all other processors, please

contact your merchant bank or processor directly.

Character length and limitations: 6 characters

RESPTEXT The raw text returned by the processor which corresponds to the returned

HOSTCODE. This field is not normalized and is returned when VERBOSITY is set

to HIGH.

Character length and limitations: 32 characters

PROCCARDSECURE The raw Buyer Authentication response returned by the processor. This field is not

normalized and is returned when VERBOSITY is set to HIGH.

Character length and limitations: 1 character

ADDLMSGS Additional error message that indicates the use of a features that has been disabled.

Character length and limitations: Up to 1048 characters. Typically 50 characters.

PAYMENTTYPE (PayPal only.) Returns instant if the payment is instant or echeck if the payment

is delayed (DP) on the PayPal processor.

Character length and limitations: 7-character string

CORRELATIONID (PayPal only.) Value used for tracking this Direct Payment transaction.

Character length and limitations: 13 alphanumeric characters

AMEXID Unique transaction ID returned when VERBOSITY=HIGH for tracking American

Express CAPN transactions on non-PayPal processors.

NOTE:Used by merchants who authorize transactions through the Gateway but settle

through a third-party solution.

Character length and limitations: 15 numeric characters

AMEXPOSDATA Value returned for American Express CAPN transactions when VERBOSITY=HIGH

on non-PayPal processors.

NOTE:Used only by merchants who authorize through the Gateway but settle

through a third-party solution.

Character length and limitations: 12 alphanumeric characters

AMT This field returns the transaction amount or if performing a partial authorization it

will return the amount approved for the partial authorization.

ORIGAMT Partial authorizations: Original amount submitted for authorization.

Field Description

Transaction Responses

Address Verification Service Responses From PayPal

90 31 July 2012 Gateway Developer Guide and Reference

Address Verification Service Responses From PayPal

The following table compares the detailed response the PayPal processor returns for address

verification to the normalized response value (Y, N, or X) that AVSADDR and AVSZIP return. To

obtain the PayPal processor value, set the VERBOSITY parameter to HIGH. The processor

value is returned in the PROCAVS response parameter.

CARDTYPE The credit card type. Is returned in an inquiry response when you send a VERBOSITY

request parameter value of HIGH.

Is one of the following values for currently used cards:

-0 = Visa

-1 = MasterCard

-2 = Discover

-3 = American Express

-4 = Diner’s Club

-5 = JCB

EMAILMATCH Verifies whether the BILLTOEMAIL value sent is what is on file with the processor.

(American Express processor only)

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

PHONEMATCH Verifies whether the BILLTOPHONENUM value sent is what is on file with the

processor. (American Express processor only)

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

EXTRSPMSG Additional processor-related messages.

TRANSTIME Time of the transaction. The following is an example response in the format returned:

TRANSTIME=2010-08-11 22:53:18

Character length and limitations: See example

DUPLICATE Is returned with one of the following values:

-DUPLICATE=2 — ORDERID has already been submitted in a previous request

with the same ORDERID.

-DUPLICATE=1 — The request ID has already been submitted for a previous

request.

-DUPLICATE=-1 — The Gateway database is not available. PayPal cannot

determine whether this is a duplicate order or request.

DATE_TO_SETTLE The date a transaction will settle. This parameter is returned in the response for

inquiry transactions only (TRXTYPE=I).

Field Description

Gateway Developer Guide and Reference 31 July 2012 91

Transaction Responses

Address Verification Service Responses From PayPal 8

The following is an example Authorization request string that sets VERBOSITY to HIGH.

Payflow returns the PROCAVS value in the response.

TRXTYPE=A&BILLTOSTREET=123 Main St&BILLTOZIP=00382&TENDER=C&PARTNER=PayPal&

USER=SuperMerchant&PWD=SuperUserPassword&AMT=1.00&ACCT=4111111111111111&EXP

DATE=1215&INVNUM=PONUM1&VERBOSITY=HIGH

The PROCAVS value is returned in the response.

RESULT=0&PNREF=VFHA0FF94691&RESPMSG=Approved&AUTHCODE=245PNI&AVSADDR=Y&AVSZ

IP=Y&HOSTCODE=A&PROCAVS=Y&VISACARDLEVEL=12&TRANSTIME=2011-01-12

13:54:35&AMT=1.00&ACCT=1111&EXPDATE=1215&CARDTYPE=0&IAVS=N

PayPal

processor

Address

Verification

Service code Meaning AVSADDR AVSZIP

AAddress YN

B International “A” Y N

C International “N” N N

D International “X” Y Y

E Not allowed for MOTO (Internet/Phone)

transactions

F UK-specific “X” Y Y

G Global Unavailable X X

I International Unavailable X X

NNo NN

P Postal (International “Z”) N Y

RRetry XX

S Service not Supported X X

U Unavailable X X

WWhole Zip N Y

X Exact Match Y Y

YYes YY

ZZip NY

All other X X

Transaction Responses

Card Security Code Results

92 31 July 2012 Gateway Developer Guide and Reference

Card Security Code Results

Normalized Card Security Code Results

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

The CVV2MATCH parameter returns Y, N, or X.

The following table shows the detailed results that the PayPal processor returns for card

security codes. To obtain the PayPal processor value, set the VERBOSITY parameter to HIGH.

The processor value is returned in the PROCCVV2 response parameter.

PayPal Card Security Code Results

The following table shows the detailed results the PayPal processor returnes for card security

codes. To obtain the PayPal processor value, set the VERBOSITY parameter to HIGH. The

processor value is returned in the PROCCVV2 response parameter.

PayPal Processor CVV2 Code

PayPal Processor Code

Description PROCVV2MATCH

M Match Y

NNo MatchN

P Not Processed X

S Service Not Supported X

U Unavailable X

X No Response X

All other X

PayPal Processor CVV2 Code

PayPal Processor Code

Description PROCVV2MATCH

M Match Y

NNo MatchN

P Not Processed X

S Service Not Supported X

U Unavailable X

Gateway Developer Guide and Reference 31 July 2012 93

Transaction Responses

BALAMT Response and Stored Value Cards 8

BALAMT Response and Stored Value Cards

Transactions meeting American Express reporting and statement requirements may return

BALAMT when the transaction involves a stored value card. Stored value cards typically are

offered as gift cards, allowing the customer to spend any amount up to the balance remaining

on the card. A card must be active and not compromised for BALAMT to return the card

balance. If the card is used to purchase merchandise exceeding the card balance, American

Express declines the transaction and returns the card balance in BALAMT.

NOTE:Not all processors support BALAMT when a transaction involves a stored value card.

American Express Stored Value Card Example

The following authorization request is for a purchase of 123.00.

TRXTYPE=A&TENDER=C&PWD=x1y2z3&PARTNER=PayPal&VENDOR=SuperMerchant&USER=Supe

rMerchant&ACCT=5555555555554444&EXPDATE=1215&AMT=123.00&BILLTOSTREET=5199 M

APLE&BILLTOZIP=94588

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

RESULT=12&PNREF=VXYZ01234567&RESPMSG=DECLINED&BALANCE=99.00&AVSADDR=Y&AVSZI

P=N

PNREF

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.

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

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

transactions for authorization (TRXTYPE=A) and sale (TRXTYPE=S).

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

X No Response X

All other X

PayPal Processor CVV2 Code

PayPal Processor Code

Description PROCVV2MATCH

Transaction Responses

RESULT Values and RESPMSG Text

94 31 July 2012 Gateway Developer Guide and Reference

-VADE0B248932

-ACRAF23DB3C4

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

question mark (?). A PNREF value 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 is the first response parameter returned in the response string. The

value of RESULT indicates the overall status of the transaction attempt:

-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 that a zero dollar authorization is successful.

-A value less than 0 indicates that a communication error occurred. In this case, no

transaction is attempted.

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

the following table).

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

To obtain the raw response code and message returned by the processor set VERBOSITY to

HIGH in your request and capture the response values of the HOSTCODE and RESPTEXT

parameters.

For PayPal Processor Only:

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

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

application. See the PayPal API documentation on x.com for detailed information on

corrective actions.

-When RESULT=104, log in to the PayPal website to determine whether the transaction

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

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 x.com for

information on corrective actions.

Gateway Developer Guide and Reference 31 July 2012 95

Transaction Responses

RESULT Values and RESPMSG Text 8

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

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

-Invalid Processor information entered. Contact merchant bank to verify.

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

update the allowed IP addresses.

-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

23 Invalid account number. Check credit card number and bank account number and re-

submit.

24 Invalid expiration date. Check card expiration date and re-submit.

RESULT RESPMSG and Explanation

Transaction Responses

RESULT Values and RESPMSG Text

96 31 July 2012 Gateway Developer Guide and Reference

25 Invalid Host Mapping. Error is caused by one or more of the following:

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

with your merchant bank to accept this card type.

-You are trying to process an Express Checkout transaction when your account is not

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

your account.

26 Invalid vendor account. 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.

27 Insufficient partner permissions

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

52 Permission issue. Attempting to perform a transaction type, such as Sale or

Authorization, that is not allowed for this account.

99 General error. See RESPMSG.

100 Transaction type not supported by host

101 Time-out value too small

PayPal Australia: Invalid transaction returned from host (can be treated as an invalid

transaction or a decline)

102 Processor not available

The financial host was unable to communicate with the external processor. These

transactions do not make it out of the Payflow network and will not settle or appear on

processor reports.

RESULT RESPMSG and Explanation

Gateway Developer Guide and Reference 31 July 2012 97

Transaction Responses

RESULT Values and RESPMSG Text 8

103 Error reading response from host

The financial host could not interpret the response from the processor. This error can

result in an uncaptured authorization if the transaction is an authorization or a sale,

except on the following processors:

-PayPal Australia: Time-out reversal logic should reverse the transaction. According

to PayPal Australia, this is a best effort and is not guaranteed.

-Global Payments Central, Citi Bank Singapore: Time-out reversal logic should

reverse the transaction.

-PayPal: The transaction might settle. There is no time-out reversal process on

PayPal.

104 Timeout waiting for processor response.

Try your transaction again.

The Payflow gateway sent the transaction to the processor, but the processor did not

respond in the allotted time. This error can result in an uncaptured authorization if the

transaction is an authorization or a sale, except on the following processors:

-PayPal Australia: Time-out reversal logic should reverse the transaction. According

to PayPal Australia, this is a best effort and is not guaranteed.

-Global Payments Central, Citi Bank Singapore: Time-out reversal logic should

reverse the transaction.

-PayPal: The transaction might settle. There is no time-out reversal process on

PayPal.

105 Credit error. Make sure you have not already credited this transaction, or that this

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

authorization.)

106 Host not available

The Payflow transaction server was unable to communicate with the financial host.

This error is an internal failure, and the transaction will not make it to the processor.

107 Duplicate suppression time-out

108 Void error. 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

The Payflow transaction server times out waiting for a financial host to respond. This

error can result in uncaptured authorizations on all platforms, or settled sales on PayPal

Australia, Global Payments Central, and PayPal.

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.

RESULT RESPMSG and Explanation

Transaction Responses

RESULT Values and RESPMSG Text

98 31 July 2012 Gateway Developer Guide and Reference

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

on the cardholder’s account.

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

transactions only.

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

cardholder’s account.

115 System busy, try again later

116 VPS Internal error. Failed to lock terminal number. For Moneris Solutions, another

transaction or settlement is in process. Rerun the transaction later.

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

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

NOTE:RESULT value 126 indicates that a transaction triggered a fraud 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.

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.

To eliminate RESULT 126, turn the filters off.

For more information, see the fraud documentation for your payments solution.

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

RESULT RESPMSG and Explanation

Gateway Developer Guide and Reference 31 July 2012 99

Transaction Responses

RESULT Values and RESPMSG Text 8

150 Issuing bank timed out

FDRA reported a timeout between their system and the bank. This error will be

reversed by time-out reversal. According to PayPal Australia, this is a best effort and is

not guaranteed.

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

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

RESULT RESPMSG and Explanation

Transaction Responses

RESULT Values and RESPMSG Text

100 31 July 2012 Gateway Developer Guide and Reference

RESULT Values For Communications Errors

A RESULT 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. For information on firewall configuration, see

“Preparing the Payflow Gateway Client Application” on page 41. A value of -1 or -2 can also

be possible if the Gateway servers are unavailable, or you specified an incorrect server or

socket pair. A value of -1 can also result when there are internet connectivity errors. Contact

Customer Service regarding any other errors.

Details of the response message may vary slightly from the message shown in the table,

depending on your SDK integration.

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

1052 Buyer Authentication Service — Validate Authentication failed: This PARES was

already validated for a previous Validate Authentication transaction

RESULT Description

-1 Failed to connect to host

-2 Failed to resolve hostname

-5 Failed to initialize SSL context

RESULT RESPMSG and Explanation

Gateway Developer Guide and Reference 31 July 2012 101

Transaction Responses

RESULT Values and RESPMSG Text 8

-6 Parameter list format error: & in name

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

-8 SSL failed to connect to host

-9 SSL read failed

-10 SSL write failed

-11 Proxy authorization failed

-12 Timeout waiting for response

-13 Select failure

-14 Too many connections

-15 Failed to set socket options

-20 Proxy read failed

-21 Proxy write failed

-22 Failed to initialize 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 Invalid 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

RESULT Description

Transaction Responses

RESULT Values and RESPMSG Text

102 31 July 2012 Gateway Developer Guide and Reference

-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

RESULT Description

Gateway Developer Guide and Reference 31 July 2012 103

AProcessors Requiring Additional

Transaction Parameters

Additional parameters are those required by individual processors beyond the core parameters.

Parameters are organized alphabetically by processor.

-“American Express Additional Credit Card Parameters” on page 103

-“Elavon Additional Credit Card Parameters” on page 109

-“First Data Merchant Services Nashville, Additional Credit Card Parameters” on page 110

-“First Data Merchant Services North, Additional Credit Card Parameters” on page 110

-“Heartland, Additional Credit Card Parameters” on page 111

-“Litle Additional Credit Card Parameters” on page 111

-“Merchant e-Solutions, Additional Credit Card Parameters” on page 113

-“Paymentech Salem (New Hampshire) Additional Credit Card Parameters for American

Express” on page 113

-“PayPal Credit Card Transaction Request Parameters” on page 115

-“SecureNet Additional Credit Card Parameters for American Express” on page 120

-“Vantiv Additional Credit Card Parameters” on page 125

-“WorldPay Additional Credit Card Parameters” on page 127

American Express Additional Credit Card Parameters

In addition to the core credit card parameters, American Express accepts the parameters

described below to meet AMEX reporting and statement requirements.

PayPal recommends that you include these parameters if you would like to impact what

appears on AMEX statements and reports.

NOTE:The PayPal processor does not support SWIPE (card-present) transactions.

Retail Transaction Advice Addendum (for SWIPE transactions)

Field Description

L_DESCn(Optional) Description of this line-item (n is a line item number from 1 to 6).

Character length and limitations: 19 alphanumeric characters

Processors Requiring Additional Transaction Parameters

American Express Additional Credit Card Parameters

104 31 July 2012 Gateway Developer Guide and Reference

Internet Transaction Data

L_AMTn(Optional) Amount of this line-item (n is a line item number from 1 to 6).

Character length and limitations: 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. 12 numeric characters

L_QTYn(Optional) Quantity of this line-item (n is a line item number from 1 to 6).

Character length and limitations: 3 numeric characters

Field Description

BILLTOEMAIL (Optional) Account holder’s email address.

Character length and limitations: 60 alphanumeric characters

BILLTOPHONENUM (Optional) Account holder’s telephone number.

Character length and limitations: 10 characters

PHONETYPE (Optional) Telephone company provided ANI information identifier digits indicating

the telephone call type. Examples: cellular (61-63), payphone (27)

Character length and limitations: 2 characters

CUSTHOSTNAME (Optional) Name of the server that the account holder is connected to. Example:

PHX.QW.AOL.COM.

Character length and limitations: 60 alphanumeric and special characters

CUSTBROWSER (Optional) Name of the server that the account holder is connected to. Example:

MOZILLA/4.0~(COMPATIBLE;~MSIE~5.0;~WINDOWS~95)

Character length and limitations: 60 alphanumeric and special characters

CUSTIP (Optional) Account holder’s IP address.

Character length and limitations: 15 alphanumeric and special characters

SHIPTOCOUNTRY (Optional) Numeric country code of ship-to country. Example: USA: 840.

Character length and limitations: 3 characters

SHIPMETHOD (Optional) 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 (Optional) Merchant product SKU.

Character length and limitations: 15 alphanumeric characters

Field Description

Gateway Developer Guide and Reference 31 July 2012 105

Processors Requiring Additional Transaction Parameters

American Express Additional Credit Card Parameters A

Address Verification Service Parameters

Location Transaction Advice Addendum Parameters

Field Description

BILLTOSTREET (Optional) Account holder’s street address (number and street name).

Character length and limitations: 20 characters

BILLTOZIP (Optional) Account holder’s 5- to 9-digit ZIP (postal) code excluding spaces,

dashes, and non-numeric characters. Example: 951121737

Character length and limitations: 9 characters

BILLTOPHONENUM (Optional) Account holder’s telephone number. The formats are:

-xxx-xxx-xxxx (US numbers)

-+xxxxxxxxxxx (international numbers)

Character length and limitations: 10 characters

SHIPTOFIRSTNAME (Optional) First name in the shipping address.

Character length and limitations: 30 characters

SHIPTOLASTNAME (Optional) Last name in the shipping address.

Character length and limitations: 30 characters

SHIPTOSTREET (Optional) Shipping street address.

Character length and limitations: 30 characters

SHIPTOCOUNTRY (Optional) Numeric country code of ship-to country. Example: USA: 840.

Character length and limitations: 3 alphanumeric characters

SHIPTOZIP (Optional) Shipping 5- to 9-digit zip (postal) code excluding spaces, dashes, and

non-numeric characters. Example: 951121737

Character length and limitations: 9 alphanumeric characters

SHIPTOPHONENUM (Optional) Shipping telephone number.

Character length and limitations: 10 alphanumeric characters

Field Description

MERCHANTNAME (Optional) Name of merchant.

Character length and limitations: 38 alphanumeric characters

MERCHANTSTREET (Optional) Merchant’s street address (number and street name).

Character length and limitations: 38 alphanumeric characters. If more than 38

characters, use proper and meaningful abbreviation. Do not truncate.

Processors Requiring Additional Transaction Parameters

American Express Additional Credit Card Parameters

106 31 July 2012 Gateway Developer Guide and Reference

MERCHANTCITY (Optional) The name of the city were the transaction took place.

-If you are a third-party biller (bill for services or goods rendered by another

entity), you must enter the name of the city in which the seller is located.

-If you are a mail order, phone order, or internet industry, you may substitute the

name of the city in which the merchant’s order processing facility is located.

Character length and limitations: 21 alphanumeric characters. If more than 21

characters, use proper and meaningful abbreviation. Do not truncate.

MERCHANTSTATE (Optional) The region code that corresponds to the state, province, or country

subdivision of the merchant location where the transaction took place.

Region code examples:

-CA = California, USA

-NS = Nova Scotia, Canada

-COS = Colima Mexico

If you are a third-party biller (bill for services or goods rendered by another entity),

you must enter the region code that corresponds to the state, province, or country

subdivision in which the seller is located.

Character length and limitations: 3 alphanumeric characters

MERCHANTZIP (Optional) The 5- to 9-digit zip (postal) code excluding spaces, dashes, and non-

numeric characters where the transaction took place.

If you are a third-party biller (bill for services or goods rendered by another entity),

you must enter the postal code that corresponds to the seller’s location.

Character length and limitations: 15 alphanumeric characters

MERCHANTCOUNTRYCODE (Optional) Country code of the location where the transaction took place.

Character length and limitations: 3 alphanumeric characters

MERCHANTLOCATIONID (Optional)Merchant-assigned store or location number (or name) that uniquely

identifies where the transaction took place.

Character length and limitations: 15 alphanumeric characters

MERCHANTID (Required) American Express-assigned service establishment number used to identify

and facilitate payments to merchants.

Character length and limitations: 15 alphanumeric characters.

MERCHANTCONTACTINFO (Optional) Merchant’s telephone number or web address. (URLs and e-mail addresses

may be lowercase, as appropriate.) This entry may appear on the descriptive bill on

the card-member’s statement, or may be used to resolve billing inquiries and disputes.

NOTE:American Express strongly recommends that aggregators (third-parties who

bill for goods or services rendered by another entity) always fill in this field

with the URL, e-mail address, or telephone number of the contact responsible

for resolving disputes or inquiries.

Character length and limitations: 40 alphanumeric characters

Field Description

Gateway Developer Guide and Reference 31 July 2012 107

Processors Requiring Additional Transaction Parameters

American Express Additional Credit Card Parameters A

Transaction Advice Detail Parameters

Airline Passenger Data Parameters

Field Description

ADDLAMTn(Optional) Detail of a charge where n is a value from 1 - 5. Use for additional

breakdown of the amount.

Character length and limitations: 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. 12 numeric characters

ADDLAMTTYPEn(Optional) A 3-digit code indicating the type of the corresponding charge detail,

where n is a value from 1 - 5.

Character length and limitations: 3 numeric characters

Field Description

AIR-DEPARTUREDATE (Optional) Departure date in the format YYYYMMDD.

Character length and limitations: 8 alphanumeric characters

AIR-PASSENGERNAME (Optional) Name of the passenger in the following format with fields separated by a

space: surname firstname middleinitial title

Character length and limitations: 60 alphanumeric characters

AIR-ORIGIN (Optional) Airport code of the originating airport. For a list of airport codes, see

http://www.world-airport-codes.com/alphabetical/airport-code/a.html.

NOTE:Present day airport codes are three characters in length. The five character

length is designed to allow for future expansion

Character length and limitations: 5 alphanumeric characters

AIR-DESTINATION (Optional) 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/airport-code/a.html.

NOTE:Present day airport codes are three characters in length. The five character

length is designed to allow for future expansion

Character length and limitations: 5 alphanumeric characters

AIR-NUMBEROFCITIES (Optional) 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.

Processors Requiring Additional Transaction Parameters

American Express Additional Credit Card Parameters

108 31 July 2012 Gateway Developer Guide and Reference

American Express Other Parameters

AIR-ROUTINGCITYn(Optional) Airport codes of each city in this flight including cities of origin and

destination, where n is a value from 1 to 10.

Character length and limitations: 5 alphanumeric characters

AIR-CARRIERn(Optional) 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 http://en.wikipedia.org/wiki/Airline_codes-

All

Character length and limitations: 24 alphanumeric characters

AIR-FAREBASIS (Optional) List discounts associated with the travel.

Character length and limitations: 24 alphanumeric characters

AIR-

NUMBEROFPASSENGERS

(Optional) Number of passengers on this trip.

Character length and limitations: numeric

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

-Y = yes

-N = no

Character length and limitations: 1 alphanumeric character

AIR-RESERVATIONCODE (Optional) Code assigned to the travel reservation before the ticket was purchased.

Character length and limitations: 15 alphanumeric characters

Field Description

BILLTOFIRSTNAME (Optional) 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).

Character length and limitations: 13 alphanumeric characters

BILLTOLASTNAME (Optional) Account holder's last name.

Character length and limitations: 13 alphanumeric characters

Field Description

Gateway Developer Guide and Reference 31 July 2012 109

Processors Requiring Additional Transaction Parameters

Elavon Additional Credit Card Parameters A

Elavon Additional Credit Card Parameters

In addition to the core credit card parameters, Elavon (formerly Nova) accepts the parameter

described below.

INVNUM (Optional) 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.

Character length and limitations: 9 alphanumeric characters

ORDERDATE (Optional) Specifies an order date.

Character length and limitations: 6 numeric characters

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

ORDERDATETIME (Optional) Specifies an order time and date.

Character length and limitations: 19 alphanumeric characters

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.

Field Description

RECURRING (Optional) Identifies the transaction as recurring. This value does not activate the

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

Character length and limitations: 1 alphanumeric character (Y or N)

Field Description

Processors Requiring Additional Transaction Parameters

First Data Merchant Services Nashville, Additional Credit Card Parameters

110 31 July 2012 Gateway Developer Guide and Reference

First Data Merchant Services Nashville, Additional Credit Card

Parameters

In addition to the core credit card parameters, First Data Merchant Services (FDMS) Nashville

accepts the parameters described below.

First Data Merchant Services North, Additional Credit Card

Parameters

In addition to the core credit card parameters, First Data Merchant Services (FDMS) North

accepts the parameters described

Field Description

INVNUM (Optional) 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.

Character length and limitations: 9 alphanumeric characters

Field Description

DESC (Optional) Use the DESC* parameters to pass in your DBA name and other data

describing the transaction. This information will be displayed in the account holder’s

statement.

NOTE:Note: FDMS North passes the descriptive data to the card associations with

the following character lengths:

Visa: 25

MasterCard: 22

AMEX: 20

DISC: 22

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

consult the card association.

Character length and limitations: 25 alphanumeric characters

MERCHDESCR (Optional) Use this parameter to pass in your DBA name and other data describing

the transaction. This information is usually displayed in the account holder’s

statement.

Character length and limitations: 25 alphanumeric characters

Gateway Developer Guide and Reference 31 July 2012 111

Processors Requiring Additional Transaction Parameters

Heartland, Additional Credit Card Parameters A

Heartland, Additional Credit Card Parameters

In addition to the core credit card parameters, Heartland accepts the parameters described

below.

Litle Additional Credit Card Parameters

MERCHSVC (Optional) Defaults to the city where the merchant outlet is located for retail and to

the merchant’s phone number for non-retail. For example, 800 111-1111. This

information is usually displayed in the account holder’s statement.

Character length and limitations: 13 alphanumeric characters

Field Description

INVNUM (Optional) 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.

NOTE:Not supported by Payflow Link.

Character length and limitations: 17 alphanumeric characters

MERCHDESCR (Optional) Use this parameter to pass in your DBA name and other data describing

the transaction (default: merchant name). This information is usually displayed in the

account holder’s statement.

Character length and limitations: 25 alphanumeric characters

MERCHSVC (Optional) Defaults to the city where the merchant outlet is located for retail and to

the merchant’s phone number for non-retail. For example, 800 111-1111. This

information is usually displayed in the account holder’s statement.

Character length and limitations: 13 alphanumeric characters

Field Description

AUTHDATE Required for Force transactions. Authorization date.

Character length and limitations: 11alphanumeric characters

CUSTOMERID (Optional) Customer identification.

Character length and limitations: 18 alphanumeric characters

Field Description

Processors Requiring Additional Transaction Parameters

Litle Additional Credit Card Parameters

112 31 July 2012 Gateway Developer Guide and Reference

INVNUM (Optional) Merchant invoice number. The merchant invoice number is used for

authorizations. If you do not provide an invoice number, the transaction ID (PNREF)

will be submitted.

Character length and limitations: 20 alphanumeric characters

MERCHANTCITY (Optional) The name of the city were the transaction took place.

- If you are a third-party biller (bill for services or goods rendered by another

entity), you must enter the name of the city in which the seller is located.

- If you are a mail order, phone order, or internet industry, you may substitute the

name of the city in which the merchant’s order processing facility is located.

Character length and limitations: 21 alphanumeric characters

MERCHANTURL (Optional) Merchant’s website. This information is usually displayed in the account

holder’s statement.

Character length and limitations: 40 alphanumeric characters

MERCHDESCR (Optional) Use this parameter to pass in your DBA name and other data describing

the transaction. This information is usually displayed in the account holder’s

statement.

Character length and limitations: 25 alphanumeric characters

MERCHSVC (Optional) Defaults to the city where the merchant outlet is located for retail and to

the merchant’s phone number for non-retail. For example, 800 111-1111. This

information is usually displayed in the account holder’s statement.

Character length and limitations: 13 alphanumeric characters

PONUM (Optional) Purchase order number.

Character length and limitations: 25 alphanumeric characters

REPORTGROUP (Optional) Category that the transaction is in, for example, coffee mugs. This field is

for your own use.

Character length and limitations: 25 alphanumeric characters

BILLTOSTREET2 (Optional) Second street address.

Character length and limitations: 35 alphanumeric characters

BILLTOSTREET3 (Optional) Third street address.

Character length and limitations: 35 alphanumeric characters

TAXAMT (Optional) Total tax amount.

Character length and limitations: 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. 12 numeric characters

TAXEXEMPT (Optional) Indicates whether the customer is tax exempt. It is one of the following

values:

-Y – The customer is tax exempt.

-N – The customer is not tax exempt (default).

Character length and limitations: 1 alpha character

Field Description

Gateway Developer Guide and Reference 31 July 2012 113

Processors Requiring Additional Transaction Parameters

Merchant e-Solutions, Additional Credit Card Parameters A

Merchant e-Solutions, Additional Credit Card Parameters

In addition to the core credit card parameters, Merchant e-Solutions accepts the parameters

described below.

Paymentech Salem (New Hampshire) Additional Credit Card

Parameters for American Express

In addition to the core credit card parameters, Paymentech Salem accepts the parameters to

meet American Express statement and reporting requirements described below.

Internet Transaction Data Parameters

Field Description

INVNUM (Optional) 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.

NOTE:Not supported by Payflow Link.

Character length and limitations: 17 alphanumeric characters

MERCHDESCR (Optional) Use this parameter to pass in your DBA name and other data describing

the transaction (default: merchant name). This information is usually displayed in the

account holder’s statement.

Character length and limitations: 25 alphanumeric characters

MERCHSVC (Optional) Defaults to the city where the merchant outlet is located for retail and to

the merchant’s phone number for non-retail. For example, 800 111-1111. This

information is usually displayed in the account holder’s statement.

Character length and limitations: 13 alphanumeric characters

Field Description

BILLTOEMAIL (Optional) Account holder’s email address.

Character length and limitations: 60 alphanumeric characters

BILLTOPHONENUM (Optional) Account holder’s telephone number.

Character length and limitations: 20 characters

PHONETYPE (Optional) Telephone company provided ANI information identifier digits indicating

the telephone call type. Examples: cellular (61-63), payphone (27)

Character length and limitations: 2 characters

Processors Requiring Additional Transaction Parameters

Paymentech Salem (New Hampshire) Additional Credit Card Parameters for American Express

114 31 July 2012 Gateway Developer Guide and Reference

AVS Parameters

CUSTHOSTNAME (Optional) Name of the server that the account holder is connected to. Example:

PHX.QW.AOL.COM.

Character length and limitations: 60 alphanumeric and special characters

CUSTBROWSER (Optional) Name of the server that the account holder is connected to. Example:

MOZILLA/4.0~(COMPATIBLE;~MSIE~5.0;~WINDOWS~95)

Character length and limitations: 60 alphanumeric and special characters

CUSTIP (Optional) Account holder’s IP address.

Character length and limitations: 15 alphanumeric and special characters

SHIPTOCOUNTRY (Optional) Numeric country code of ship-to country. Example: USA: 840.

Character length and limitations: 3 alphanumeric characters

SHIPMETHOD (Optional) 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 (Optional) Merchant product SKU.

Character length and limitations: 15 alphanumeric and special characters

Field Description

BILLTOSTREET (Optional) Account holder’s street address (number and street name).

Character length and limitations: 20 characters

BILLTOZIP (Optional) Account holder’s 5- to 9-digit ZIP (postal) code excluding spaces,

dashes, and non-numeric characters. Example: 951121737

Character length and limitations: 9 characters

BILLTOPHONENUM (Optional) Account holder’s telephone number. The formats are:

-xxx-xxx-xxxx (US numbers)

-+xxxxxxxxxxx (international numbers)

Character length and limitations: 10 characters

SHIPTOFIRSTNAME (Optional) First name in the shipping address.

Character length and limitations: 30 characters

SHIPTOLASTNAME (Optional) Last name in the shipping address.

Character length and limitations: 30 characters

Field Description

Gateway Developer Guide and Reference 31 July 2012 115

Processors Requiring Additional Transaction Parameters

PayPal Credit Card Transaction Request Parameters A

Additional Credit Card Parameters for M Record

PayPal Credit Card Transaction Request Parameters

In addition to the core credit card parameters, PayPal accepts the parameters described below.

SHIPTOSTREET (Optional) Shipping street address.

Character length and limitations: 30 characters

SHIPTOCOUNTRY (Optional) Numeric country code of ship-to country. Example: USA: 840.

Character length and limitations: 3 alphanumeric characters

SHIPTOZIP (Optional) Shipping 5- to 9-digit zip (postal) code excluding spaces, dashes, and

non-numeric characters. Example: 951121737

Character length and limitations: 9 alphanumeric characters

SHIPTOPHONENUM (Optional) Shipping telephone number.

Character length and limitations: 10 alphanumeric characters

Field Description

MERCHDESCR (Optional) Use this parameter to pass in your DBA name and other data describing

the transaction. This information is usually displayed in the account holder’s

statement.

Character length and limitations: 25 alphanumeric characters

MERCHSVC (Optional) Defaults to the city where the merchant outlet is located for retail and to

the merchant’s phone number for non-retail. For example, 800 111-1111. This

information is usually displayed in the account holder’s statement.

Character length and limitations: 13 alphanumeric characters

Parameter Description

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

-0 = Visa

-1 = MasterCard

-2 = Discover

-3 = AMEX

-4 = DinersClub

-5 = JCB

-8 = Other

Field Description

Processors Requiring Additional Transaction Parameters

PayPal Credit Card Transaction Request Parameters

116 31 July 2012 Gateway Developer Guide and Reference

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

AMT=ITEMAMT + TAXAMT + FREIGHTAMT + HANDLINGAMT + INSURANCEAMT

- DISCOUNT

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

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

Limitations: Must not exceed $10,000 USD in any currency. Nine numeric characers

plus decimal (.) character. No currency symbol. Specify the exact amount to the cent

using a decimal point—use 34.00, not 34. Do not include comma separators—use

1199.95 not 1,199.95.

Nine numeric characters plus decimal.

CURRENCY (Required) The currency code.

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

currency.

Limitations: Three characters.

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

transactions.

Limitations: 32 alphanumeric characters.

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

website. This value is optional but recommended.

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

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

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

to make. The values are:

-Y (default)

-N

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

reauthorized transaction is automatically voided.

Limitations: 12-character alphanumeric string.

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

Limitations: 256-character alphanumeric string.

EMAIL (Optional) Email address of payer.

Limitations: 127 alphanumeric characters.

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

Limitations: 127 alphanumeric characters.

Parameter Description

Gateway Developer Guide and Reference 31 July 2012 117

Processors Requiring Additional Transaction Parameters

PayPal Credit Card Transaction Request Parameters A

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

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

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

Specify the exact amount to the cent using a decimal point—use 34.00, not 34. Do not

include comma separators—use 1199.95 not 1,199.95.

Limitations: Nine numeric characters plus decimal.

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

TAXAMT=L_QTY0*L_TAXAMT0 + L_QTY1*L_TAXAMT1 +...L_QTYn

*L_TAXAMTn

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

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

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

Specify the exact amount to the cent using a decimal point—use 34.00, not 34. Do not

include comma separators—use 1199.95 not 1,199.95.

Nine numeric characters plus decimal.

FREIGHTAMT (Optional) Total shipping costs for this order.

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

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

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

Specify the exact amount to the cent using a decimal point—use 34.00, not 34. Do not

include comma separators—use 1199.95 not 1,199.95.

Nine numeric characters plus decimal.

HANDLINGAMT (Optional) Total handling costs for this order.

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

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

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

Specify the exact amount to the cent using a decimal point—use 34.00, not 34. Do not

include comma separators—use 1199.95 not 1,199.95.

Nine numeric characters plus decimal.

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

amount.

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

Specify the exact amount to the cent using a decimal point—use 34.00, not 34. Do not

include comma separators—use 1199.95 not 1,199.95.

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

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

Specify the exact amount to the cent using a decimal point—use 34.00, not 34. Do not

include comma separators—use 1199.95 not 1,199.95.

Parameter Description

Processors Requiring Additional Transaction Parameters

PayPal Credit Card Transaction Request Parameters

118 31 July 2012 Gateway Developer Guide and Reference

L_NAMEn(Optional) Line-item name.

NOTE:To enable line-item support, you must contact Merchant Technical Support at

http://www.paypal.com/mts

Character length and limitations: 36 alphanumeric characters.

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

cooking utensils.

NOTE:To enable line-item support, you must contact Merchant Technical Support at

http://www.paypal.com/mts

Limitations: 127 alphanumeric characters.

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

a positive or a negative value but not 0.

NOTE:To enable line-item support, you must contact Merchant Technical Support at

http://www.paypal.com/mts

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

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

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

Specify the exact amount to the cent using a decimal point—use 34.00, not 34. Do not

include comma separators—use 1199.95 not 1,199.95.

Nine numeric characters plus decimal.

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

NOTE:To enable line-item support, you must contact Merchant Technical Support at

http://www.paypal.com/mts

Limitations: 10-character integer.

L_SKUn(Optional) Product number.

NOTE:To enable line-item support, you must contact Merchant Technical Support at

http://www.paypal.com/mts

Limitations: 18-characters.

L_TAXAMTn(Optional) Line-item tax amount.

NOTE:To enable line-item support, you must contact Merchant Technical Support at

http://www.paypal.com/mts

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

Specify the exact amount to the cent using a decimal point—use 34.00, not 34. Do not

include comma separators—use 1199.95 not 1,199.95.

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

PayPal records this session token as an additional means to detect possible fraud.

Limitations: 64 characters.

Parameter Description

Gateway Developer Guide and Reference 31 July 2012 119

Processors Requiring Additional Transaction Parameters

PayPal Credit Card Transaction Request Parameters A

NOTIFYURL (Optional) Your URL for receiving Instant Payment Notification (IPN) about this

transaction. If you do not specify NOTIFYURL in the request, the notification URL

from your Merchant Profile is used, if one exists.

Limitations: 2048 alphanumeric characters.

ORDERDESC (Optional) Description of items the customer is purchasing.

Limitations: 127 alphanumeric characters.

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

-F = First occurrence

-S = Subsequent occurrence (default)

Limitations: One alpha character.

BILLTOCITY (Conditional) Bill-to city address.

Limitations: 40 alphanumeric characters.

NOTE:Some merchants maybe required to pass this billing information. Please test

your integration first to determine if the billing information fields are

required.

BILLTOSTATE (Conditional) Bill-to state or province address.

Limitations: 40 alphanumeric characters.

NOTE:Some merchants maybe required to pass this billing information. Please test

your integration first to determine if the billing information fields are

required.

BILLTOCOUNTRY (Conditional) Bill-to country address.

Limitations: 2 alphanumeric characters.

NOTE:Some merchants maybe required to pass this billing information. Please test

your integration first to determine if the billing information fields are

required.

SHIPTOSTREET (Optional) Ship-to street address.

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

SHIPTOSTATE, you must pass in the complete set (that is, SHIPTOSTREET,

SHIPTOCITY, SHIPTOSTATE, SHIPTOCOUNTRY, and SHIPTOZIP).

Limitations: 30-character string.

SHIPTOCITY (Optional) Ship-to city address.

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

SHIPTOSTATE, you must pass in the complete set (that is, SHIPTOSTREET,

SHIPTOCITY, SHIPTOSTATE, SHIPTOCOUNTRY, and SHIPTOZIP).

Limitations: 40-character string.

Parameter Description

Processors Requiring Additional Transaction Parameters

SecureNet Additional Credit Card Parameters for American Express

120 31 July 2012 Gateway Developer Guide and Reference

SecureNet Additional Credit Card Parameters for American

Express

In addition to the core credit card parameters, SecureNet accepts the parameters described

below to meet American Express reporting and statement requirements.

Retail Transaction Advice Addendum (for SWIPE transactions)

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

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

SHIPTOSTATE, you must pass in the complete set (that is, SHIPTOSTREET,

SHIPTOCITY, SHIPTOSTATE, SHIPTOCOUNTRY, and SHIPTOZIP).

Limitations: 10-character string.

SHIPTOCOUNTRY (Optional) Ship-to country code.

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

SHIPTOSTATE, you must pass in the complete set (that is, SHIPTOSTREET,

SHIPTOCITY, SHIPTOSTATE, SHIPTOCOUNTRY, and SHIPTOZIP).

Limitations: Two alpha characters.

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

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

SHIPTOSTATE, you must pass in the complete set (that is, SHIPTOSTREET,

SHIPTOCITY, SHIPTOSTATE, SHIPTOCOUNTRY, and SHIPTOZIP).

Limitations: 20-character string.

Field Description

L_DESCn(Optional) Description of this line-item (n is a line item number from 1 to 6).

Character length and limitations: 19 alphanumeric characters

L_AMTn(Optional) Amount of this line-item (n is a line item number from 1 to 6).

Character length and limitations: 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. 12 numeric characters

L_QTYn(Optional) Quantity of this line-item (n is a line item number from 1 to 6).

Character length and limitations: 3 numeric characters

Parameter Description

Gateway Developer Guide and Reference 31 July 2012 121

Processors Requiring Additional Transaction Parameters

SecureNet Additional Credit Card Parameters for American Express A

Internet Transaction Data

AVS Parameters

Field Description

BILLTOEMAIL (Optional) Account holder’s email address.

Character length and limitations: 60 alphanumeric characters

BILLTOPHONENUM (Optional) Account holder’s telephone number.

Character length and limitations: 10 characters

PHONETYPE (Optional) Telephone company provided ANI information identifier digits indicating

the telephone call type. Examples: cellular (61-63), payphone (27).

Character length and limitations: 2 alphanumeric characters

CUSTHOSTNAME (Optional) Name of the server that the account holder is connected to. Example:

PHX.QW.AOL.COM.

Character length and limitations: 60 alphanumeric and special characters

CUSTBROWSER (Optional) Name of the server that the account holder is connected to. Example:

MOZILLA/4.0~(COMPATIBLE;~MSIE~5.0;~WINDOWS~95)

Character length and limitations: 60 alphanumeric and special characters

CUSTIP (Optional) Account holder’s IP address.

Character length and limitations: 15 alphanumeric and special characters

SHIPTOCOUNTRY (Optional) Numeric country code of ship-to country. Example: USA: 840.

Character length and limitations: 3 alphanumeric characters

SHIPMETHOD (Optional) 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

Field Description

BILLTOSTREET (Optional) Account holder’s street address (number and street name).

Character length and limitations: 20 characters

BILLTOZIP (Optional) Account holder’s 5- to 9-digit ZIP (postal) code excluding spaces,

dashes, and non-numeric characters. Example: 951121737

Character length and limitations: 9 characters

Processors Requiring Additional Transaction Parameters

SecureNet Additional Credit Card Parameters for American Express

122 31 July 2012 Gateway Developer Guide and Reference