Paypal Gateway 2013 Developers Guide Payflow Developer And Reference

Gateway - 2013 - Developer Guide and Reference payflowgateway_2013_ug Free User Guide for PayPal Software, Manual

2015-07-27

: Paypal Paypal-Gateway-2013-Developers-Guide-777945 paypal-gateway-2013-developers-guide-777945 paypal pdf

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

Gateway Developer
Guide and Reference
PayPal Payments Advanced
PayPal Payments Pro
Payflow Pro
Payflow Link
Last updated: 07 February 2013
Gateway Developer Guide and Reference
Document Number: 200045.en_US-201302
© 2013 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other
trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
Copyright © PayPal. All rights reserved. PayPal (Europe) S.à r.l. et Cie., S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard
Royal, L-2449, Luxembourg, R.C.S. Luxembourg B 118 349.
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval
of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.
Notice of non-liability:
PayPal, Inc. is providing the information 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 07 February 2013 3
Content
Chapter Preface . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Who Should Use This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Chapter 1 Introducing the Gateway Checkout Solutions . . . . . . . .23
About the Gateway Checkout Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Summary of the Gateway Checkout Solutions . . . . . . . . . . . . . . . . . . . . . 23
Gateway Product Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
About the Gateway Transaction Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
About Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Secure Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Hosted Checkout Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
PCI Compliance Without Hosted Pages: Transparent Redirect . . . . . . . . . . . . . 27
Processing Platforms Supporting Card-Present Transactions . . . . . . . . . . . . . . . . 28
Supported Payment Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Supported Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Recurring Billing Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Fraud Protection Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Chapter 2 Secure Token . . . . . . . . . . . . . . . . . . . . . . . .31
About the Secure Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Integrating the Secure Token With the Hosted Checkout Pages . . . . . . . . . . . . . . 31
Integrating the Secure Token Without the Hosted Checkout Pages: Transparent Redirect . 32
Secure Token Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Posting To the Hosted Checkout Page . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Chapter 3 Configuring Hosted Checkout Pages . . . . . . . . . . . .37
Configuring Hosted Checkout Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Content
407 February 2013 Gateway Developer Guide and Reference
Configuring Hosted Pages Using PayPal Manager . . . . . . . . . . . . . . . . . . . . . 37
Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Customize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Integrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Using a Secure Token to Pass Hosted Pages Customization Parameters . . . . . . . . . 41
Using the PARMLIST Parameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Hosted Pages and Mobile Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Mobile Optimized Checkout Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Silent Posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Force Silent Post Confirmation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Data Returned by the Silent Post Features . . . . . . . . . . . . . . . . . . . . . . . 48
Passing Other Data to Your Server Using Post or Silent Post . . . . . . . . . . . . . . . . 48
Chapter 4 Payflow SDK . . . . . . . . . . . . . . . . . . . . . . . . .49
Preparing the Payflow Gateway Client Application . . . . . . . . . . . . . . . . . . . . . 49
Activating Your Payflow Gateway Account. . . . . . . . . . . . . . . . . . . . . . . . . . 50
Host URL Addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Chapter 5 Sending a Simple Transaction to the Server . . . . . . . .51
About Name-Value Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Using Special Characters In Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Name-Value Parameter Syntax Guidelines . . . . . . . . . . . . . . . . . . . . . . . 52
Do Not URL Encode Name-Value Parameter Data . . . . . . . . . . . . . . . . . . . 52
Payflow Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
User Parameter Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Sale Transaction Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Typical Sale Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Formatting Payflow Gateway Transactions . . . . . . . . . . . . . . . . . . . . . . . . . 54
Chapter 6 Submitting Credit Card Transactions . . . . . . . . . . . .55
Obtaining an Internet Merchant Account . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
About Credit Card Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Credit Card Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Planning Your Gateway Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Complying With E-commerce Indicator . . . . . . . . . . . . . . . . . . . . . . . . . 58
Handling Credit Card Type Information . . . . . . . . . . . . . . . . . . . . . . . . . 58
Gateway Developer Guide and Reference 07 February 2013 5
Content
Core Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Submitting Account Verifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
When To Use Account Verifications . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Required Account Verification Parameters . . . . . . . . . . . . . . . . . . . . . . . 62
Example Account Verification String . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Submitting Authorization/Delayed Capture Transactions . . . . . . . . . . . . . . . . . . 63
When to Use Authorization/Delayed Capture Transactions . . . . . . . . . . . . . . . 63
Required Authorization Transaction Parameters . . . . . . . . . . . . . . . . . . . . 64
Typical Authorization Transaction Parameter String . . . . . . . . . . . . . . . . . . . 64
Submitting Balance Inquiry Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Processing Platforms Supporting Balance Inquiry Transactions . . . . . . . . . . . . 65
Required Balance Inquiry Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Example Balance Inquiry Transaction String . . . . . . . . . . . . . . . . . . . . . . 65
Submitting Card Present (SWIPE) Transactions. . . . . . . . . . . . . . . . . . . . . . . 65
Processing Platforms Supporting Card-Present Transactions. . . . . . . . . . . . . . 66
Card Present Transaction Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Submitting Credit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Required Credit Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . 67
Submitting Inquiry Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
When To Use an Inquiry Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Required Parameters When Using the PNREF . . . . . . . . . . . . . . . . . . . . . 70
Inquiry Transaction Parameter String Using the PNREF . . . . . . . . . . . . . . . . 70
Required Parameters When Using the CUSTREF . . . . . . . . . . . . . . . . . . . 70
Inquiry Transaction Parameter String Using the CUSTREF . . . . . . . . . . . . . . . 71
Required Parameters When Using the Secure Token . . . . . . . . . . . . . . . . . . 71
Inquiry Parameter String Using the Secure Token . . . . . . . . . . . . . . . . . . . . 72
Submitting Partial Authorizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
When To Use Partial Authorizations . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Required Partial Authorization Parameters . . . . . . . . . . . . . . . . . . . . . . . 72
Example Partial Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Submitting Purchasing Card Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Submitting Reference Transactions (Tokenization) . . . . . . . . . . . . . . . . . . . . . 74
When To Use a Reference Transaction . . . . . . . . . . . . . . . . . . . . . . . . . 74
Transaction Types That Can Be Used As the Original Transaction . . . . . . . . . . . 75
Fields Copied From Reference Transactions . . . . . . . . . . . . . . . . . . . . . . 75
Example Reference Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Data Upload - Storing Credit Card Data on the Gateway Server . . . . . . . . . . . . 76
Submitting Sale Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
When To Use a Sale Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Content
607 February 2013 Gateway Developer Guide and Reference
Additional Parameters For Sale Transactions . . . . . . . . . . . . . . . . . . . . . . 77
Typical Sale Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . . 78
Submitting Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
About Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Ways to Send Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . 79
Submitting Voice Authorization Transactions . . . . . . . . . . . . . . . . . . . . . . . . 80
When To Use a Voice Authorization Transaction . . . . . . . . . . . . . . . . . . . . 80
Required Voice Authorization Transaction Parameters . . . . . . . . . . . . . . . . . 80
Submitting Void Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
When To Use a Void Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Required Void Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 81
Fields Copied From the Original Transaction Into the Void Transaction. . . . . . . . . 81
Example Void Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . 82
Using Address Verification Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Example Address Verification Service Parameter String . . . . . . . . . . . . . . . . 82
Using Card Security Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Chapter 7 Testing Transactions . . . . . . . . . . . . . . . . . . . .85
Setting Up The Payflow Gateway Testing Environment . . . . . . . . . . . . . . . . . . . 85
Testing Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Processors Other Than PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Credit Card Numbers for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Testing Address Verification Service. . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Testing Card Security Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
PayPal Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Credit Card Numbers for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Result Values Based On Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Chapter 8 Transaction Responses . . . . . . . . . . . . . . . . . . .95
Credit Card Transaction Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Address Verification Service Responses From PayPal . . . . . . . . . . . . . . . . . . . 98
Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Normalized Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . .100
PayPal Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . . . .100
BALAMT Response and Stored Value Cards . . . . . . . . . . . . . . . . . . . . . . . .101
American Express Stored Value Card Example . . . . . . . . . . . . . . . . . . . . .101
PNREF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Gateway Developer Guide and Reference 07 February 2013 7
Content
RESULT Values and RESPMSG Text . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
RESULT Values For Communications Errors . . . . . . . . . . . . . . . . . . . . . .108
Chapter A Processors Requiring Additional Transaction Parameters 111
American Express Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . 111
Retail Transaction Advice Addendum (for SWIPE transactions) . . . . . . . . . . . . 111
Internet Transaction Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112
Address Verification Service Parameters . . . . . . . . . . . . . . . . . . . . . . . . 113
Location Transaction Advice Addendum Parameters . . . . . . . . . . . . . . . . . . 113
Transaction Advice Detail Parameters. . . . . . . . . . . . . . . . . . . . . . . . . .115
Airline Passenger Data Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .115
American Express Other Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Elavon Additional Credit Card Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . 117
First Data Merchant Services Nashville, Additional Credit Card Parameters . . . . . . . . 118
First Data Merchant Services North, Additional Credit Card Parameters . . . . . . . . . .118
Heartland, Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . 119
Litle Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Merchant e-Solutions, Additional Credit Card Parameters. . . . . . . . . . . . . . . . . .121
Paymentech Salem (New Hampshire) Additional Credit Card Parameters for American
Express . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
Internet Transaction Data Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .121
AVS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Additional Credit Card Parameters for M Record . . . . . . . . . . . . . . . . . . . .123
PayPal Credit Card Transaction Request Parameters . . . . . . . . . . . . . . . . . . . .123
SecureNet Additional Credit Card Parameters for American Express . . . . . . . . . . . .128
Retail Transaction Advice Addendum (for SWIPE transactions) . . . . . . . . . . . .128
Internet Transaction Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
AVS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
Location Transaction Advice Addendum Parameters . . . . . . . . . . . . . . . . . .130
Transaction Advice Detail Parameters. . . . . . . . . . . . . . . . . . . . . . . . . .131
Airline Passenger Data Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Other Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
Vantiv Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .133
Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .133
Soft Merchant Descriptor Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .134
WorldPay Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . .135
Chapter B TeleCheck Electronic Check Processing . . . . . . . . . 137
Content
807 February 2013 Gateway Developer Guide and Reference
TeleCheck NFTF Overview of Services . . . . . . . . . . . . . . . . . . . . . . . . . . .137
TeleCheck NFTF Processing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . .137
NFTF Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
NFTF Processing Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
NFTF Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
TeleCheck Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140
Required TeleCheck Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .141
Testing TeleCheck Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
Example Test Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
Preparing for TeleCheck Production Transactions . . . . . . . . . . . . . . . . . . . . . .144
Responses to TeleCheck Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . .144
Transaction Responses Common to All Tender Types . . . . . . . . . . . . . . . . .144
Response Code Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Sale Response Code Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Adjustment Code Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Response Codes For Status Response Packets . . . . . . . . . . . . . . . . . . . .146
TeleCheck Authorization Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . .147
Authorization – Sales Consent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
Authorization – Sales Decline/Error . . . . . . . . . . . . . . . . . . . . . . . . . . .150
Chapter C Submitting Purchasing Card Level 2 and 3 Transactions . 151
About Purchasing Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
About Program Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
Accepted BIN Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
About American Express Purchasing Card Transactions . . . . . . . . . . . . . . . . . .152
Supported Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
Avoiding Downgrade. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
Submitting Successful Level 3 Transactions . . . . . . . . . . . . . . . . . . . . . .153
Edit Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
Accepted BIN Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
American Express Purchasing Card Transaction Processing . . . . . . . . . . . . . . . .154
American Express Level 2 Parameters for American Express . . . . . . . . . . . . .154
Example American Express Level 2 Transaction Parameter String . . . . . . . . . . .157
American Express Level 3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . .157
Example American Express Level 3 Transaction Parameter String . . . . . . . . . . .159
Elavon (Formerly Nova) Purchasing Card Transaction Processing . . . . . . . . . . . . .160
Elavon Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Elavon Additional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Gateway Developer Guide and Reference 07 February 2013 9
Content
Example Elavon Level 2 Transaction Parameter String . . . . . . . . . . . . . . . . .161
First Data Merchant Services (FDMS) Nashville Purchasing Card Transaction Processing.161
FDMS Nashville Commercial Card Parameters . . . . . . . . . . . . . . . . . . . . .161
First Data Merchant Services (FDMS) North Purchasing Card Transaction Processing . .162
FDMS North Purchasing Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .162
FDMS North Purchasing Card Line Item Parameters . . . . . . . . . . . . . . . . . .163
First Data Merchant Services South (FDMS) Purchasing Card Transaction Processing . .163
FDMS South Level 2 and Level 3 Purchasing Card Parameters . . . . . . . . . . . .164
FDMS South Line Item Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .165
Example FDMS South Purchasing Card Level 2 and 3 Parameter String . . . . . . . .166
Example FDMS South Line Item Parameter String . . . . . . . . . . . . . . . . . . .166
Global Payments - Central Purchasing Card Transaction Processing . . . . . . . . . . . .167
Global Payments - Central Level 2 Parameters . . . . . . . . . . . . . . . . . . . . .167
Global Payments - East Purchasing Card Transaction Processing . . . . . . . . . . . . .167
Global Payments - East Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . .167
Example Global Payments - East Level 2 Visa or MasterCard Transaction Parameter String
168
Heartland Purchasing Card Transaction Processing. . . . . . . . . . . . . . . . . . . . .168
Heartland Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168
Heartland Level 3 MasterCard Parameters . . . . . . . . . . . . . . . . . . . . . . .169
Heartland Level 3 Visa Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .171
Litle Purchasing Card Transaction Processing. . . . . . . . . . . . . . . . . . . . . . . .174
Litle Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .174
Litle Level 3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Merchant e-Solutions Purchasing Card Transaction Processing . . . . . . . . . . . . . .177
Merchant e-Solutions Level 2 Parameters. . . . . . . . . . . . . . . . . . . . . . . .177
Merchant e-Solutions Level 3 MasterCard Parameters . . . . . . . . . . . . . . . . .177
Merchant e-Solutions Level 3 Visa Parameters . . . . . . . . . . . . . . . . . . . . .180
Paymentech Salem (New Hampshire) Purchasing Card Transaction Processing . . . . . .182
Paymentech Salem (New Hampshire) Level 2 Parameters for American Express . . .182
Paymentech Salem (New Hampshire) Level 3 Purchasing Card Parameters. . . . . .185
Paymentech Tampa Level 2 Purchasing Card Transaction Processing . . . . . . . . . . .188
Paymentech Tampa Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . .189
Example Paymentech Tampa Level 2 Visa and MasterCard Transaction Parameter String
189
SecureNet Purchasing Card Transaction Processing . . . . . . . . . . . . . . . . . . . .189
SecureNet Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189
SecureNet Level 3 MasterCard Parameters . . . . . . . . . . . . . . . . . . . . . . .190
SecureNet Acquiring Solutions Level 3 Visa Parameters . . . . . . . . . . . . . . . .192
Content
10 07 February 2013 Gateway Developer Guide and Reference
TSYS Acquiring Solutions Purchasing Card Transaction Processing . . . . . . . . . . . .195
TSYS Acquiring Solutions Level 2 Parameters . . . . . . . . . . . . . . . . . . . . .195
TSYS Acquiring Solutions Level 3 MasterCard Parameters. . . . . . . . . . . . . . .196
TSYS Acquiring Solutions Level 3 Visa Parameters. . . . . . . . . . . . . . . . . . .198
Vantiv Purchasing Card Transaction Processing . . . . . . . . . . . . . . . . . . . . . .201
Vantiv Purchasing Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201
Vantiv Purchasing Card Line Item Parameters . . . . . . . . . . . . . . . . . . . . .201
WorldPay Purchasing Cards Transaction Processing . . . . . . . . . . . . . . . . . . . .202
WorldPay Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .202
WorldPay Level 3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204
Chapter D Payflow Header Parameters . . . . . . . . . . . . . . . . 207
Sending Requests Directly to PayPal Bypassing Payflow . . . . . . . . . . . . . . . . . .207
Posting Transactions Directly Without the Payflow SDK. . . . . . . . . . . . . . . . . . .208
The Payflow Message Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . .208
Payflow Message Protocol Headers . . . . . . . . . . . . . . . . . . . . . . . . . . .209
Transaction Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211
Integrator-Provided Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212
Chapter E VERBOSITY: Processor-Specific Transaction Results . . 215
Chapter F ISO Country Codes . . . . . . . . . . . . . . . . . . . . 217
Chapter G Codes Used by FDMS South Only . . . . . . . . . . . . . 219
MasterCard Country Codes for FDMS South Only . . . . . . . . . . . . . . . . . . . . .219
Visa Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226
Units of Measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233
Chapter H PayPal Acquirer . . . . . . . . . . . . . . . . . . . . . . 241
Countries and Regions Supported by PayPal . . . . . . . . . . . . . . . . . . . . . . . .241
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241
PayPal Currency Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241
Appendix I Additional Processor Information . . . . . . . . . . . . . 243
Moneris Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243
Gateway Developer Guide and Reference 07 February 2013 11
Content
Chapter J Payflow Link Migration . . . . . . . . . . . . . . . . . . 245
Migrating from a legacy Payflow Link Integration . . . . . . . . . . . . . . . . . . . . . .245
Chapter K Payflow Gateway MagTek Parameters . . . . . . . . . . . 247
MagTek MagneSafe Secure Card Readers and Qwick Codes . . . . . . . . . . . . . . .247
MagneSafe Secure Card Reader Authenticators . . . . . . . . . . . . . . . . . . . .247
MagTek Qwick Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248
Passing Encrypted Card Swipe Data and Qwick Codes to the Payflow Gateway . . . . . .248
Encrypted Card Swipe Payflow Example . . . . . . . . . . . . . . . . . . . . . . . .249
Qwick Code (PCode) Payflow Example . . . . . . . . . . . . . . . . . . . . . . . . .249
Parameters for Encrypted Card Swipe Transactions . . . . . . . . . . . . . . . . . . . .250
Parameters for MagTek Qwick Code (PCode) Transactions. . . . . . . . . . . . . . . . .253
MagTek Error Codes and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254
Content
12 07 February 2013 Gateway Developer Guide and Reference
Gateway Developer Guide and Reference 07 February 2013 13
Preface
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.
Related Documentation
For additional information on the Gateway payments solutions:
-See PayPal Manager at:
https://manager.paypal.com/
-For more information on Payflow documentation, examples, and very current information,
see the PayPal developer site at the following URL:
https://www.x.com/developers/paypal
Intended Audience
This guide provides Gateway payments solutions to readers who:
-Are web or application developers
-Have a background in payments services
Preface
Intended Audience
14 07 February 2013 Gateway Developer Guide and Reference
Who Should Use This Document
This comprehensive developer guide includes integration information for multiple Gateway
solutions. Legacy Payflow Link features are not included in this guide. For legacy Payflow
Link features refer to the Payflow Link Users Guide. Additionally, all the Gateway features
explained in this guide are not necessarily available to every Gateway customer. This section
will help you determine whether you should use this document and which sections of the
document are relevant to you.
To view the Gateway solutions available to you, login to PayPal Manager at
https://manager.paypal.com/. PayPal Manager displays your Gateway Services in the Service
Summary box.
-Payflow Link
Payflow Link customers can choose PayPal or another merchant bank to process their
transactions via the Payflow Gateway.
A) Legacy Payflow Link users will see the following in the Service Summary box in PayPal
Manager:
Payflow Link
If you are a legacy Payflow Link user, do not use this guide; instead, use the Payflow Link
Users Guide.
B) New Payflow Link users will see the following in the Service Summary box in PayPal
Manager:
Hosted Checkout Pages & Payflow SDK/API (Limited Access). (If PayPal Payments
Advanced is also listed, then you are not a Payflow Link customer).
Gateway Developer Guide and Reference 07 February 2013 15
Preface
Intended Audience
New Payflow Link users who are using the Secure Token or the API should use this guide.
However, new Payflow Link users who are using the legacy Payflow Link input tag
integration should use the Payflow Link Users Guide instead.
Limited API Access means you can perform all API functions except for Sales and
Authorization transactions. For Sales and Authorization type transactions you must use the
Hosted Checkout Pages.
-Payflow Pro
Payflow Pro customers can choose PayPal or another merchant bank to process their
transactions via the Gateway.
A) Legacy Payflow Pro users will see the following in the Service Summary box in PayPal
Manager:
Payflow Pro
Legacy Payflow Pro users should use this guide; however, these users can only use the API
integration and do not have the Hosted Checkout Pages service. If you are a legacy
Payflow Pro user, you should skip the chapter on Hosted Checkout Pages - “Configuring
Hosted Checkout Pages” on page 37.
B) New Payflow Pro users can take advantage of all of the Gateway features including
Hosted Checkout Pages. These users will see the following in the Service Summary box in
PayPal Manager:
Hosted Checkout Pages & Payflow SDK/API (Full Access)
Preface
Intended Audience
16 07 February 2013 Gateway Developer Guide and Reference
-PayPal Payments Advanced
Transactions submitted by PayPal Payments Advanced customers are processed through
the Gateway with PayPal acting as the merchant bank. PayPal Payments Advanced users
will see the following in the Service Summary box in PayPal Manager:
PayPal Payments Advanced with Hosted Checkout Pages & Payflow SDK/API (Limited
Access)
Limited API Access means you can perform all API functions except for Sales and
Authorization transactions. For Sales and Authorization type transactions you must use
Hosted Checkout Pages.
-PayPal Payments Pro
Transactions submitted by PayPal Payments Pro customers are processed through the
Gateway with PayPal acting as the merchant bank. PayPal Payments Pro users can use all
of the Gateway features supported by PayPal. These users will see the following in the
Service Summary box in PayPal Manager:
PayPal Payments Pro with Hosted Checkout Pages & Payflow SDK/API (Full Access)
Gateway Developer Guide and Reference 07 February 2013 17
Preface
Revision History
Revision History
Revision History for the Gateway Developer Guide and Reference:
Date Description
28 Jan 2013 Added a new Appendix on Payflow Header Parameters.
Added information about duplicate parameters in the
Name-Value Parameter Syntax Guidelines.
In the Hosted Pages Chapter, added the Passing Other
Data to Your Server Using Post or Silent Post section,
and clarified that Silent Posts are returned for both
approved and declined transactions.
Updated the Payflow Link legacy parameters and the
equivalent Payflow parameters parameter table.
Removed legacy Payflow Link parameters with
identical Payflow equivalents.
Updated the description of the BILLTOSTATE and
SHIPTOSTATE parameters in the Core Credit Card
Parameters table.
Added a note to the introduction of the Submitting
Credit Card Transactions chapter.
Revised the introduction to the Payflow SDK chapter.
Updated some of the external links in the guide.
Corrected the format of the ORDERDATE parameter in
TSYS Acquiring Solutions Level 3 Visa Extended Data.
28 Dec 2012 Updated the description of the Drivers Licencse - DL
field in Required TeleCheck Parameters.
11 Dec 2012 Added info on forcing the Cancel URL with layout
template C to Configuring Hosted Pages Using PayPal
Manager.
Added Secure Token error codes to Secure Token Errors
and to RESULT Values and RESPMSG Text.
04 Oct 2012 Added a new section on Hosted Pages and Mobile
Browsers and updated the Configuring Hosted
Checkout Pages chapter.
Added a new section: Supported Languages.
Added a new section: Using the PARMLIST Parameter.
Added information to the Host URL Addresses section.
29 Aug 2012 Added the Payflow Gateway MagTek Parameters
Appendix.
31 July 2012 Added a list of Setup Params and Customize Params.
These parameters override PayPal Manager settings for
Hosted Pages.
Preface
Revision History
18 07 February 2013 Gateway Developer Guide and Reference
Briefly explained the differences between Submitting
Credit Transactions and Submitting Void Transactions.
Updated the parameters in the Payflow Link legacy
parameters and the equivalent Payflow parameters
table.
Added DATE_TO_SETTLE to Credit Card Transaction
Responses parameters table.
Added a note to the About Credit Card Processing
section.
23 July 2012 Added the Bill Me Later feature to the Gateway Product
Details section.
16 July 2012 Updated required value for BILLTOCITY,
BILLTOSTATE & BILLTOCOUNTRY in PayPal Credit
Card Transaction Request Parameters table.
June 2012 Who Should Use This Document section added to the
Preface.
Integrating the Secure Token Without the Hosted
Checkout Pages: Transparent Redirect section:
corrected value of SILENTTRAN to “True
Silent Posts section added to Hosted Checkout Pages
chapter.
ISO Country Codes: removed the legacy paramater
CORPCOUNTRY
May 2012 Added new sections to the Testing Transactions
chapter:
Testing Address Verification ServiceTesting Card
Security Code
Added PayPal Acquirer chapter:
Contains links to PayPal API Ref country and currency
codes
May 2012 (cont.) Document maintenance: Added cross-references and
external links; reorganized content; removed no longer
applicable content.
April 2012 Added new transaction type:
Balance Inquiry(TRXTYPE=B) can be used to obtain
the balance of a pre-paid card.
Date Description
Gateway Developer Guide and Reference 07 February 2013 19
Preface
Revision History
Updated TeleCheck chapter:
Updated MICR values in Testing TeleCheck
Transactions section
Added TeleCheck Adjustment Response Code Values
table
Updated parameters and examples:
Added a description for response parameters
HOSTCODE, RESPTEXT, PROCCARDSECURE,
ADDLMSGS and an explanation on how to use these
parameters to obtain the processors raw response codes
and response messages.
Changed Litle parameters from STREET2,STREET3 to
BILLTOSTREET2, BILLTOSTREET3
Corrected description of MERCHSVC parameter for
FDMS North, Heartland, Litle, Merchant e-Solutions,
Paymentech Salem
Updated examples and removed legacy parameters to
include:FIRSTNAME, LASTNAME, STREET, CITY,
STATE, ZIP, COUNTRY
Updated processor and entity names:
Vantiv, previously known as Fifth Third Processing
Solutions
PayPal Australia, previously known as First Data
Australia
January 2012 Added new processors:
First Third International
Heartland Payment Systems
Planet Payment
SecureNet
TeleCheck
WorldPay
Added new transaction types:
TRXTYPE=L can be used to upload credit card data,
easing PCI compliance. You can store the resulting
PNREF locally for use in performing reference
transactions.
Date Description
Preface
Revision History
20 07 February 2013 Gateway Developer Guide and Reference
January 2012 (cont.) Added request NVPs:
ADDLAMTn
ADDLAMTTYPEn
AUTHDATE
CATTYPE
CONTACTLESS
CUSTDATA
CUSTOMERID
CUSTOMERNUMBER
DISCOUNT
DUTYAMT
DLNAME
DLNUM
DOB
L_ALTTAXAMTn
L_ALTTAXIDn
L_ALTTAXRATEn
L_CARRIERSERVICELEVELCODEn
L_COMMCODEn
L_EXTAMTn
L_PRODCODEn
L_TAXTYPEn
ORDERID
MERCHANTDESCR
MERCHANTINVNUM
MERCHANTNAME
MERCHANTURL
MERCHANTVATNUM
MERCHANTZIP
MISCDATA
REPORTGROUP
SILENTTRAN
STREET3
VATINVNUM
VATTAXAMT
VATTAXRATE
Added response NVPs:
DUPLICATE (response)
EXTRMSG (response)
Date Description
Gateway Developer Guide and Reference 07 February 2013 21
Preface
Revision History
January 2012 (cont.) Added concepts:
Gateway Product Solutions - PayPal Payments
Advanced, PayPal Payments Pro, Payflow Pro, Payflow
Link
Transaction Flow
Transparent Redirect
February 2011 First publication.
Date Description
Preface
Revision History
22 07 February 2013 Gateway Developer Guide and Reference
Gateway Developer Guide and Reference 07 February 2013 23
1Introducing the Gateway
Checkout Solutions
The Gateway provides checkout solutions for novice and advanced use. It provides merchants
with a rich set of options to handle payment transactions.
-“About the Gateway Checkout Solutions” on page 23
-“About the Gateway Transaction Flow” on page 25
-“About Security” on page 26
-“Processing Platforms Supporting Card-Present Transactions” on page 28
-“Supported Payment Types” on page 29
-“Recurring Billing Service” on page 30
About the Gateway Checkout Solutions
Gateway checkout consists of the following four solutions:
-Payflow Link
-Payflow Pro
-PayPal Payments Advanced
-PayPal Payments Pro
Summary of the Gateway Checkout Solutions
Below is a basic comparison of the Gateway checkout solutions:
-Payflow Link uses hosted checkout pages to send transactions to a supported processor.
Merchants can use the Payflow SDK APIs to perform all transactions except authorization
and sale transactions. By using hosted pages with a secure token, the merchant adheres to
compliance rules for handling customer data in a secure way: data is stored on PayPal so
that it is not exposed to compromise.
-Payflow Pro can send transactions to a number of different supported processors,
requirements for which are described in this documentation. Merchants select a supported
processor and obtain an acquiring bank. Typically merchants integrate with, and have full
access to, the Payflow SDK or use HTTPS to send transactions to the processor. Using
hosted pages is an option.
-PayPal Payments Advanced uses web pages hosted by PayPal (also known as hosted
checkout pages) to send transactions to the PayPal processor. With PayPal Payments
Advanced, PayPal is the acquiring bank. By using hosted checkout pages with a secure
Introducing the Gateway Checkout Solutions
About the Gateway Checkout Solutions
1
24 07 February 2013 Gateway Developer Guide and Reference
token, the merchant adheres to compliance rules for handling customer data in a secure
way: data is stored on PayPal so that it is not exposed to compromise.
-Like PayPal Payments Advanced, PayPal Payments Pro sends transactions to the PayPal
processor and PayPal is the acquiring bank. Using hosted checkout pages is an option.
Typically merchants integrate with the Payflow SDK or use HTTPS to send transactions to
the PayPal processor.
NOTE:PayPal strongly recommends that all users of Gateway checkout solutions take
advantage of the secure token and the hosted checkout pages. Doing so provides
automatic compliance with processing card industry (PCI) standards for protecting
cardholder data.
Gateway Product Details
The table below compares how the Gateway checkout solutions support payment processing
features.
Feature
PayPal Payments Advanced
Payflow Link
PayPal Payments Pro
Payflow Pro
Hosted checkout page (including an
iFrame version)
Yes Yes
PayPal payments Included Optional
Bill Me Later payments
(Available to US merchants only on
Hosted checkout pages.)
Included Optional
PayPal branding on full page templates Yes Optional
Transparent Redirect No Yes
Supports PayPal as a processor and an
acquirer
Yes Yes
Credit and debit cards Yes Yes
Level 2 and Level 3 purchase cards Yes Yes
TeleCheck (guaranteed electronic
checks)
No Yes
ACH (electronic checks) No Yes
Virtual Terminal support, including
card-present data passage
Yes Yes
Virtual Terminal Payflow Link only Yes
API Limited access (no authorization
or sale)
Full access
Gateway Developer Guide and Reference 07 February 2013 25
Introducing the Gateway Checkout Solutions
About the Gateway Transaction Flow 1
About the Gateway Transaction Flow
The traditional transaction flow is as follows. Numbers correspond to numbers in the figure.
1. At your website, the customer clicks Buy to purchase merchandise.
2. You send the transaction request to the Gateway server.
3. The Gateway sends the transaction to the payment processing network.
4. Your processor sends the response back to the Gateway server and processes the
transaction (obtains the payment from the customer bank and deposits it in the merchant
bank).
5. The Gateway server returns the response to your website.
6. Your website displays the result to the customer.
You can use the core transaction parameters supported by all Gateway processors described in
this dcumentation to send transaction data to your processor. In addition:
Reference transactions (Tokenization) Yes Yes
Secure token to preset hosted checkout
page
Yes Yes
Reporting APIs Yes Yes
Desktop integration Yes Yes
Recurring billing Yes Yes
Basic fraud protection Yes Yes
Advanced fraud protection Yes Yes
Partner/channel distribution support
(Partner Manager, registration, XML
registration) resale and referral
Yes Yes
Feature
PayPal Payments Advanced
Payflow Link
PayPal Payments Pro
Payflow Pro
Introducing the Gateway Checkout Solutions
About Security
1
26 07 February 2013 Gateway Developer Guide and Reference
-Each Gateway processor may support various additional parameters beyond the core set
that you can send in transaction requests.
-Your processor may also support purchasing cards (credit cards employers issue for
business-related charges). Purchasing card Level 2 and Level 3 parameters provide
specialized reporting so an employer can monitor card use. The parameter information may
appear on the customers statement or describe line items in greater detail. Be sure to check
for your processors Level 2 and 3 parameters in this documentation.
The sections in this documentation describing the above parameters alphabetically organize
parameters by processor name.
About Security
It is your responsibility to adhere to PCI compliance standards to protect personal information
and implement security safeguards on your website when processing payment card
transactions.
Gateway solutions make available a secure token and hosted checkout pages to help you meet
PCI compliance. Hosted pages are optional to PayPal Payments Pro and Payflow Pro users. If
you do not use a secure token or hosted pages, you must provide your own means of meeting
compliance requirements.
NOTE:PayPal Payments Advanced and Payflow Link merchants are required to use hosted
pages.
Secure Token
The secure token stores request transaction data on the Gateway server. It eliminates the need
to resend the parameter data for display in a hosted checkout page where the data might be
subject to compromise.
Hosted Checkout Pages
The Gateway enables the use of hosted checkout pages, which help you achieve PCI
compliance. The hosted checkout pages enable you to pass transaction data securely to the
server and to collect credit card acceptance data.
NOTE:You are required to use hosted pages with PayPal Payments Advanced and Payflow
Link.
The following figure shows the transaction flow when using hosted pages and a secure token.
Gateway Developer Guide and Reference 07 February 2013 27
Introducing the Gateway Checkout Solutions
About Security 1
Numbers in the figure correspond to the numbered comments below:
1. The customer clicks Buy to purchase merchandise on your website.
2. You request a secure token by passing a token ID to the Gateway server.
3. The Gateway server returns the secure token and your token ID to your website.
4. You submit the secure token and token ID in an HTTP post to pages hosted on the Gateway
server and redirect the customers browser to the hosted pages.
5. The Gateway server uses the secure token to retrieve the amount and other transaction data.
The customer submits their credit card number, expiration date, and other sensitive data
directly to the host pages rather than to your website, easing your PCI compliance
requirements.
6. The Gateway processes the payment through the payment processing network.
7. The Gateway server transparently returns the customer to the location on your website that
you specified in the request to obtain a secure token. You display the results to the
customer on your website.
NOTE:If you do not get a response from the Gateway server, submit an Inquiry transaction,
passing in the secure token to see if the transaction has completed. For details, see
“Submitting Inquiry Transactions” on page 69.
PCI Compliance Without Hosted Pages: Transparent Redirect
PayPal Payments Pro and Payflow Pro merchants who want PCI compliance while
maintaining full control over designing and hosting checkout pages on their website can use
Transparent Redirect. Transparent Redirect posts payment details silently to the Gateway
server, so this sensitive information never goes through the merchant’s website.
Introducing the Gateway Checkout Solutions
Processing Platforms Supporting Card-Present Transactions
1
28 07 February 2013 Gateway Developer Guide and Reference
Implementing Transparent Redirect is very similar to implementing hosted pages. It differs
only in the steps shown in boldface below:
1. The customer clicks Buy to purchase merchandise on your website.
2. You request a secure token by passing a secure token ID to the Gateway server. In the
request, you pass the name-value pair, SILENTTRAN=TRUE. This name-value pair
prevents the hosted pages from displaying.
3. The Gateway server returns the secure token and your token ID to your website.
4. You display the credit card fields to the customer in a checkout page on your website.
5. The customer enters their credit card number, expiration date, and other sensitive
data into the credit card fields and clicks Submit. The browser posts the payment data
directly to the Gateway server, avoiding your website and easing your PCI
compliance requirements.
NOTE:To ensure that the post goes from the browser directly to PayPal and not back to
your website, you should add scripting.
6. The Gateway processes the payment through the payment processing network.
7. The Gateway server transparently sends the customer to the location on your website that
you specified in the request to obtain a secure token. You display the results to the
customer on your website.
Processing Platforms Supporting Card-Present Transactions
The following processing platforms support card-present transactions.
American Express
American Express APAC
Elavon
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
Gateway Developer Guide and Reference 07 February 2013 29
Introducing the Gateway Checkout Solutions
Supported Payment Types 1
Supported Payment Types
Supported Languages
The Payflow Gateway only supports customer input and API parameter values that are in
regular ASCII (English language) characters. Payflow does not support extended ASCII
characters or any other character sets other than regular ASCII at this time. Additionally, the
Payflow hosted checkout pages and PayPal manager account settings pages are available in
English only. For information on a similar PayPal product that offers multi-lingual support, see
Website Payments Pro Hosted Solution.
Moneris Solutions
Paymentech Salem
Paymentech Tampa
PayPal
SecureNet
TeleCheck
TSYS Acquiring Solutions
Van t iv
WorldPay
Credit cards
PayPal (supported by PayPal’s Express Checkout product)
Pinless debit cards
Electronic checks
Check cards
Purchasing cards (also referred to as commercial cards, corporate cards, procurement cards, or business cards)
Level 2 and Level 3
Automated Clearing House (ACH). For information on performing ACH transactions, contact your PayPal Sales
Representative.
Introducing the Gateway Checkout Solutions
Recurring Billing Service
1
30 07 February 2013 Gateway Developer Guide and Reference
Recurring Billing Service
The Recurring Billing Service is a scheduled payment solution that enables you to
automatically bill your customers at regular intervals—for example, you can bill your
customers a monthly fee of $42 for 36 months with an initial fee of $129.
You enroll separately for the Recurring Billing Service. You can learn about the Recurring
Billing Service in the Payflow Pro – Recurring Billing Service Users Guide. If you already have
this service, this user guide will show you how to define and manage recurring transactions
programmatically. You can also manage Recurring Billing tasks in PayPal Manager.
Fraud Protection Service
Fraud Protection Services can help you significantly reduce the cost of fraud and the resulting
damage to your business. This service uses Fraud Protection filters to help protect you from
fraudsters using stolen or false credit card information. These filters identify potentially
fraudulent activity and let you decide whether to accept or reject the suspicious transaction.
Fraud Protection Service can also minimize the risk of hacking your customer database by
enabling you to place powerful constraints on access to and use of your PayPal Manager and
Payflow Gateway accounts.
You enroll separately for the Fraud Protection Service. You can learn more about Fraud
Protection Service in the Payflow Pro Fraud Protection Services User’s Guide. If you already have
this service, this user guide will show you how to setup Fraud Protection filters. You can also
manage some aspects of your Fraud Protection Service in PayPal Manager.
Gateway Developer Guide and Reference 07 February 2013 31
2Secure Token
This section describes the secure token.
-“Secure Token” on page 31
-“Integrating the Secure Token With the Hosted Checkout Pages” on page 31
-“Integrating the Secure Token Without the Hosted Checkout Pages: Transparent Redirect”
on page 32
-“Posting To the Hosted Checkout Page” on page 34
-“Using the PARMLIST Parameter” on page 44
About the Secure Token
Use a secure token to send non-credit card transaction data to the Gateway server for safer
storage. The secure token prevents anyone from intercepting or manipulating the data. You
must use a secure token if you use hosted checkout pages. The token is good for a one-time
transaction and is valid for 30 minutes.
NOTE:PayPal Payments Pro and Payflow Pro merchants who do not use a secure token must
host their own payment pages. When hosting your own pages, you are responsible for
meeting PCI requirements by handling data securely. PayPal Payments Advanced and
Payflow Link merchants must use a secure token with hosted checkout pages.
To obtain a secure token, pass a unique, 36-character secure token ID and set
CREATESECURETOKEN=Y in a request to the Gateway server. The Gateway server associates
your ID with a secure token and returns the token as a string of up to 32 alphanumeric
characters.
To pass the transaction data to the hosted checkout page, you pass the secure token and secure
token ID in an HTTP form post. The token and ID trigger the Gateway server to retrieve your
data and display it for customer approval.
NOTE:You cannot modify the data sent with a secure token, with one exception. You can
configure PayPal Manager to allow you to modify billing and shipping information.
Integrating the Secure Token With the Hosted Checkout Pages
To create a secure token, pass all parameters that you need to process the transaction except
for payment details parameters such as the credit card number, expiration date, and check
number. For details on transaction parameters, see “Submitting Credit Card Transactions” on
page 55. In addition, pass the following Payflow parameters to create the secure token.
Secure Token
Integrating the Secure Token Without the Hosted Checkout Pages: Transparent Redirect
2
32 07 February 2013 Gateway Developer Guide and Reference
NOTE:The secure token is valid for 30 minutes, and you can only use it one time. If you
attempt to use the token after the time limit has expired, your transaction will fail with
Result value 7, “Secure Token Expired.” If you attempt to reuse the token, you receive
an error.
1. Set SECURETOKENID to a unique alphanumeric value up to 36 characters in length.
SECURETOKENID=9a9ea8208de1413abc3d60c86cb1f4c5
2. Set CREATESECURETOKEN to the value Y to request that Payflow gateway return a token.
CREATESECURETOKEN=Y
Secure Token Example
The following is an example of a request parameter string that creates a secure token.
TRXTYPE=A&BILLTOSTREET=123 Main St.&BILLTOZIP=95131&AMT=23.45&CURRENCY=USD&
INVNUM=INV12345&PONUM=PO9876&CREATESECURETOKEN=Y&SECURETOKENID=9a9ea8208de1
413abc3d60c86cb1f4c5
The Gateway server returns SECURETOKEN and SECURETOKENID in the response. A tag
follows the SECURETOKEN to indicate the length of the token value returned.
RESULT=0&RESPMSG=Approved&SECURETOKEN[25]=Fj+1AFUWft0+I0CUFOKh5WA==&SECURET
OKENID=9a9ea8208de1413abc3d60c86cb1f4c5
Integrating the Secure Token Without the Hosted Checkout
Pages: Transparent Redirect
To use your own checkout pages while complying with PCI guidelines (sending the
customers sensitive data directly to the Gateway server), pass all parameters that you need to
process the transaction except for sensitive payment details such as the credit card number,
expiration date, and check number. For details on sending transactions, see “Submitting Credit
Card Transactions” on page 55.
In addition, pass the following 3 Payflow parameters in your request. The first 2 parameters
obtain a secure token. The third parameter implements Transparent Redirect, which
suppresses hosted pages.
NOTE:The secure token is valid for 30 minutes, and you can only use it one time. If you
attempt to use the token after the time limit has expired, your transaction will fail with
Result value 7, “Secure Token Expired.” If you attempt to reuse the token, you receive
an error.
1. Set SECURETOKENID to a unique alphanumeric value up to 36 characters in length.
SECURETOKENID=9a9ea8208de1413abc3d60c86cb1f4c5
Gateway Developer Guide and Reference 07 February 2013 33
Secure Token
Secure Token Errors 2
2. Set CREATESECURETOKEN to the value Y to request that the Gateway server return a token.
CREATESECURETOKEN=Y
3. Set SILENTTRAN to the value TRUE to suppress the display of hosted pages.
SILENTTRAN=TRUE
Transparent Redirect Example
The following is an example of an authorization parameter string that suppresses hosted pages.
TRXTYPE=A&BILLTOSTREET=123 Main St.&BILLTOZIP=95131&AMT=24.35&INVNUM=INV123
45&PONUM=PO12345&CURRENCY=USD&CREATESECURETOKEN=Y&SECURETOKENID=9a9ea8208de
1413abc3d60c86cb1f4c5&SILENTTRAN=TRUE
The Gateway server returns a SECURETOKEN and SECURETOKENID in the response. A tag
follows the SECURETOKEN to indicate the length of the token value returned.
RESULT=0&RESPMSG=Approved&SECURETOKEN[25]=Fj+1AFUWft0+I0CUFOKh5WA==&SECURET
OKENID=9a9ea8208de1413abc3d60c86cb1f4c5
When the customer enters their sensitive data into the credit card fields on your website and
clicks Submit, the browser posts the data to the Gateway server rather than to your website.
NOTE:It is highly recommended that you add scripting to ensure the the browser posts the
sensitive data directly to the PayPal Gateway server rather than to your website.
If you are using the PARMLIST parameter with the Transparent Redirect, see “Using the
PARMLIST Parameter” on page 44 for more information.
Secure Token Errors
A successful Payflow transaction will return RESULT=0 in the response. If your Secure Token
transaction is unsuccessful, you can pass the token 2 more times to Payflow before the token
expires.
A Payflow Secure Token will expire:
-If the same Secure Token is passed to Payflow a total of 3 times.
-20 minutes after the Secure Token was generated.
-When the token is used in a successful transaction.
If you receive one of the following error codes in the RESULT response parameter, then your
Secure Token has expired.
Secure Token
Posting To the Hosted Checkout Page
2
34 07 February 2013 Gateway Developer Guide and Reference
If you see a different error code in the RESULT parameter, refer to the RESULT Values and
RESPMSG Text section for more information.
Posting To the Hosted Checkout Page
To display the transaction information to the Gateway hosted checkout page, you perform an
HTTP form post.
1. Direct the HTTP post to the Gateway applications server at the following URL.
https://payflowlink.paypal.com
2. Send the following parameter data:
SECURETOKEN returned in the transaction response
SECURETOKENID
HTTP Form Post Examples
The following is an example request string that displays the transaction information to the
hosted checkout page.
<html>
<head>
<title>PageTitle</title>
</head>
<body>
<form method="post" action="https://payflowlink.paypal.com">
<input type=hidden value="Fj+1AFUWft0+I0CUFOKh5WA=="
name=SECURETOKEN/>
<input type=hidden value="9a9ea8208de1413abc3d60c86cb1f4c5"
name=SECURETOKENID/>
</form>
</body>
</html>
160 Secure Token already been used. Indicates that the secure token has expired due to
either a successful transaction or the token has been used three times while trying to
successfully process a transaction. You must generate a new secure token.
161 Transaction using secure token is already in progress. This could occur if a
customer hits the submit button two or more times before the transaction completed.
162 Secure Token Expired. The time limit of 20 minutes has expired and the token can no
longer be used.
Gateway Developer Guide and Reference 07 February 2013 35
Secure Token
Posting To the Hosted Checkout Page 2
For more information on the Payflow parameters that are used to pass information to the
Gateway hosted checkout pages, see “Using a Secure Token to Pass Hosted Pages
Customization Parameters” on page 41
The following example uses Payflow name-value pairs to pass values in a form post to the
hosted checkout pages. For details on the name-value pair strings used in this example, see
“Sending a Simple Transaction to the Server” on page 51.
<html>
<head>
<title>PageTitle</title>
</head>
<body>
<form method="post" action="https://payflowlink.paypal.com">
<input type="text" name = "SECURETOKEN" value =
"FvwEnHTYRNUSVsZRlhFpudA=="/>
<input type="text" name = "SECURETOKENID" value =
"9a9ea8208de1413abc3d60c86cb1f4c5"/>
<input type="hidden" name="PARMLIST"
value="INVNUM[8]=INV12345&AMT[5]=25.50&CURRENCY[3]=
USD&PONUM[7]=PO12345"/>
<input type="submit"/>
</form>
</center>
</body></html>
Secure Token
Posting To the Hosted Checkout Page
2
36 07 February 2013 Gateway Developer Guide and Reference
Gateway Developer Guide and Reference 07 February 2013 37
3Configuring Hosted Checkout
Pages
This chapter describes the following:
-“Configuring Hosted Checkout Pages” on page 37
-“Configuring Hosted Pages Using PayPal Manager” on page 37
-“Using a Secure Token to Pass Hosted Pages Customization Parameters” on page 41
-“Hosted Pages and Mobile Browsers” on page 45
-“Silent Posts” on page 47
-“Passing Other Data to Your Server Using Post or Silent Post” on page 48
Configuring Hosted Checkout Pages
PayPal enables you to customize the hosted checkout pages so that they reflect the look and
feel of your website. In doing so, the buyer seamlessly transitions from your website to the
PayPal hosted checkout pages to make the payment and complete the transaction. Since the
pages are hosted on PayPal servers, you do not have to capture or store credit card information
on your website, thereby helping towards achieving PCI compliance. PayPal’s hosted
checkout pages are optimized for supported desktop and mobile browsers.
NOTE:The Payflow Gateway implementation helps to achieve PCI compliance but does not
necessarily guarantee it.
There are two ways to configure hosted checkout pages:
-Logging in to PayPal Manager and making selections
-Using a secure token and passing configuration parameters in a form post
Configuring Hosted Pages Using PayPal Manager
You can specify the content of your hosted checkout pages and configure their appearance to
reflect the look and feel of your website. To do so, log into PayPal Manager and click on the
Service Settings tab. In the Hosted Checkout Pages section, you have the following options:
-Setup
-Customize
-Integrate
Configuring Hosted Checkout Pages
Configuring Hosted Pages Using PayPal Manager
3
38 07 February 2013 Gateway Developer Guide and Reference
Setup
The Setup page in PayPal Manager enables you to select the information you want to collect
from buyers and what you want displayed on your hosted checkout pages. This includes
selecting the billing and the shipping information information fields, the payment
confirmation page settings, the confirmation email details, security options and other settings.
You can perform tasks such as:
-Configure your PayPal Express Checkout display and specify email addresses for live and
test transactions.
-Determine the cancel URL and the text of the link the buyer clicks on to cancel the
payment on your website. The cancel URL is the page to which PayPal redirects your
buyers browser if the buyer does not approve the payment.
NOTE:Payflow will ignore the cancel URL field that you entered in PayPal Manager if you
select layout template C. To force Payflow to use the cancel URL field with layout
template C, in PayPal Manager, add DISPLAY_URL | before your cancel URL.
Example: DISPLAY_URL | http://www.yoursite.com/home.php
-Select the billing and shipping information fields the buyer will be required to complete
during checkout.
-Choose to display a PayPal hosted payment confirmation page or host your own
confirmation page on your website. You can also specify the paypal hosted confirmation
page header and footer text and the URL and text for the return link. Additionally, you can
choose to enable the silent post feature.
-Opt to send email receipts to the buyer for each successful transaction.
For complete details on these settings, click the Help button on the Setup page. To quickly get
get started with your hosted pages, go to the Hosted Pages Getting Started Guide on the PayPal
Gateway Developer Guide and Reference 07 February 2013 39
Configuring Hosted Checkout Pages
Configuring Hosted Pages Using PayPal Manager 3
developer portal. For more information on the Silent Post feature, go to “Silent Posts” on
page 47
Customize
The Customize page allows you to customize the layout and appearance of your hosted
checkout page. You can customize the header, background, payment method section and the
order summary column of your payment page. PayPal offers three design layouts for you to
choose from. Layout A is the default layout but you can choose any of the three layouts
offered (Layouts A, B and C).
Configuring Hosted Checkout Pages
Configuring Hosted Pages Using PayPal Manager
3
40 07 February 2013 Gateway Developer Guide and Reference
On the Customize page, you can either change the design of your existing layout, or select and
customize a different layout. To make changes, double-click on the section of the template you
are trying to modify or the corresponding Click to Edit button for that section. In the pop-up
that appears, click the color selector to change the color, or enter the appropriate URL. The
customization options vary for the different Layouts. These options are described in greater
detail in the next section: Customizing Your Layout.
After making the changes, click one of the following buttons:
-Preview - Preview the changes you have made to your layout before saving and publishing
it
-Save and Publish - Save all the changes you have made and publish the updated layout.
Your buyers will see the updated payment page.
-Cancel - Discard all the changes you have made in this session.
-Undo Changes - Discard all changes you have made since the last time you saved the
layout. Your buyers will see the last saved layout.
NOTE:You must make all modifications (including changing layouts) within the same
session, otherwise all changes will be lost and you will have to redo your changes. If
the session times out, the design of the layout will remain at the version that was last
published.
NOTE:Payflow will ignore the cancel URL field that you entered in PayPal Manager if you
select layout template C. To force Payflow to use the cancel URL field with layout
template C, in PayPal Manager, add DISPLAY_URL | before your cancel URL.
Example: DISPLAY_URL | http://www.yoursite.com/home.php
Customizing Your Layout
You can customize the appearance of the Layout template that you selected on the customize
page. These customizations apply mostly to Layouts A and B. Layout C is embedded on a
page you host in an iFrame. So for Layout C, you already control the appearance of the page.
NOTE:These customizations are not applied to the mobile version of the hosted checkout
pages.
-Header (Applicable to Layouts A and B) - You can change the following:
Header height (Applicable to Layouts A and B)
Header background color (Applicable to Layout B only)
Header font type, size (Applicable to Layouts A and B)
Header font color (Applicable to Layout B only)
Swap between displaying the business name or the business logo image
Edit business name in the header (Applicable to Layouts A and B)
Position of the business name or the logo within the header (left, centered, right)
(Applicable to Layouts A and B)
Gateway Developer Guide and Reference 07 February 2013 41
Configuring Hosted Checkout Pages
Using a Secure Token to Pass Hosted Pages Customization Parameters 3
-Page Background (Applicable to Layout B only) - You can change the following:
Background color
Footer text color
Upload a background image - .jpg, .jpeg, .gif, or .png. The maximum allowable image
size is 100kb.
Repeat image option
-Payment Method Section (Applicable to Layouts B and C) - You can change the following:
Text color of the section title (Applicable to Layout B only)
Subheader text color (Applicable to Layouts B and C)
Color of other text in this section (Applicable to Layout B only)
Section border color (Applicable to Layouts B and C)
Button color and button text color (Applicable to Layouts B and C)
-Order Summary Column (Applicable to Layout Bonly) - You can change the following:
Column background color
Upload a background image
Repeat image option
For step-by-step instructions on customizing the appearance of your checkout pages, go to
Nate’s blog post on PayPal’s developer portal: https://www.x.com/node/2750.
Integrate
This section contains links to PayPal developer resources. PayPal’s developer portal includes:
-Developer integration guides which are comprehensive product guides like this guide.
-Getting Started Guides that can help get you up and running quickly with a basic integration.
-How-to guides that walk you through a specific integration use case.
-Other useful resources such as blog posts, forums, screencasts, code samples and more.
Using a Secure Token to Pass Hosted Pages Customization
Parameters
Another way to configure your hosted checkout pages is to submit hosted checkout page
configuration parameters to the Payflow Gateway in a form post. These parameters will
override your hosted checkout page settings in PayPal Manager.
First, you will need to create a secure token. You then pass the secure token with the hosted
pages configuration parameters. To learn how to create a secure token, see the Secure Token
chapter.
Configuring Hosted Checkout Pages
Using a Secure Token to Pass Hosted Pages Customization Parameters
3
42 07 February 2013 Gateway Developer Guide and Reference
The table below describes the form post parameters that you can use to dynamically configure
the hosted checkout pages.
Setup Params
Variable Description
CANCELURL The URL that customers would go to if pressing a
Cancel link from the hosted page (Layouts A and B
only) and from the Express Checkout flow if the buyer
chooses Express Checkout as their payment method.
Maximum length: 512 characters.
CSCREQUIRED Determines if the card security code is required. Values:
TRUE or FALSE
CSCEDIT Determines if the card security code is editable. Values:
TRUE or FALSE
DISABLERECEIPT Determines if the payment confirmation / order receipt
page is a PayPal hosted page or a page on the merchant
site. For carts we recommend the carts host the order
confirmation page. Values: TRUE or FALSE
EMAILCUSTOMER Send the buyer an email confirmation or not. Default
value is FALSE.
ERRORURL The URL that customers are directed to if an error
occurs. Maximum length: 512 characters.
RETURNURL The URL that customers are directed to after a
transaction completes successfully. Maximum length:
512 characters.
SILENTPOSTURL The URL to which the Gateway will send Silent Post.
Maximum length: 512 characters.
TEMPLATE Determines whether to use one of the two redirect
templates (Layout A or B) or the embedded template
(Layout C). For Layouts A or B pass: TEMPLATEA or
TEMPLATEB. Layouts A & B auto-redirect to mobile-
optimized pages if a supported mobile browser is
detected. No action is required from the merchant for
Layouts A & B. For Layout C, pass MOBILE for the
mobile-optimized page or MINLAYOUT for the default
Layout C embedded template.
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
Gateway Developer Guide and Reference 07 February 2013 43
Configuring Hosted Checkout Pages
Using a Secure Token to Pass Hosted Pages Customization Parameters 3
Customize Params
Other HTML Post Params
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.
NOTE: This parameter will be deprecated in the future.
Instead of using this parameter to specify if you
are passing a live or test secure token, post your
form parameters to either the live URL or to the
new testing URL. See the Host URL Addresses
section for more information.
PARMLIST A HTTP Post parameter used with a secure token.
PARMLIST takes a string of name-value pairs as its
value. Payflow parses out these name-value pairs and
uses them to run the transaction. PARMLIST is
especially useful for merchants that already use this
parameter with the Payflow SDK and want to use an
existing name-value pair string. For more information
see the Using the PARMLIST Parameter section of this
guide.
SECURETOKEN/SECURETOKENID Used with the secure token.
SHOWAMOUNT If you pass in $0 amount and TRXTYPE=A, then if
SHOWAMOUNT=FALSE, Payflow will not display the
amount in the order summary table.Values:
TRUE/FALSE
Configuring Hosted Checkout Pages
Using the PARMLIST Parameter
3
44 07 February 2013 Gateway Developer Guide and Reference
Using the PARMLIST Parameter
PARMLIST is a HTTP Post parameter used with a secure token to pass information to the
Gateway hosted checkout pages. PARMLIST takes a string of name-value pairs as its value.
Payflow parses out these name-value pairs and uses them to run the transaction. PARMLIST is
especially useful for merchants that already use this parameter with the Payflow SDK and
want to use an existing name-value pair string.
PARMLIST Example
<html>
<head>
<title>PageTitle</title>
</head>
<body>
<form method="post" action="https://payflowlink.paypal.com">
<input type="hidden" name="SECURETOKEN"
value="Fj+1AFUWft0+IOCUFOKh5WA==" />
<input type="hidden" name="SECURETOKENID"
value="9a9ea8208de1413abc3d60c86cb1f4c5" />
<input type="hidden" name="MODE" value="LIVE" />
<input type="hidden" name="PARMLIST"
value="INVNUM=INV1234&AMT=25.50&CURRENCY=USD
&PONUM=PO12345" />
</form>
</body>
</html>
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 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 07 February 2013 45
Configuring Hosted Checkout Pages
Hosted Pages and Mobile Browsers 3
If you choose to use PARMLIST, then you can only pass the following 3 HTTP Post parameters
to Payflow with PARMLIST: SECURETOKEN, SECURETOKENID and MODE (optional). If you
try to pass in any other parameter (such as VERIFY=TRUE), then you will receive an error
message.
NOTE:The MODE parameter will be deprecated in the future. If you are using a test secure
token, instead of passing MODE=TEST, change the Form Action attribute value to the
testing URL: https://pilot-payflowlink.paypal.com.
If you are using Transparent Redirect with PARMLIST, you must pass the credit card
information (ACCT, EXPDATE and CSC) in the PARMLIST. For more information on
Transparent Redirect, see “Integrating the Secure Token Without the Hosted Checkout Pages:
Transparent Redirect” on page 32.
Hosted Pages and Mobile Browsers
In PayPal Manager you can select one of 3 hosted pages Layout templates: Layouts A and B
(the redirect templates) or Layout C (the embedded template). Layout A is the default Layout.
You can also dynamically select your hosted pages Layout template using the form post
TEMPLATE parameter. This will override your default Layout template set in PayPal Manager.
Please see Using a Secure Token to Pass Hosted Pages Customization Parameters for more
information on passing form post parameters to customize the checkout experience.
Mobile Optimized Checkout Pages
PayPal’s hosted checkout pages are mobile optimized for iPhone, iPod and Android devices.
This mobile optimized experience is available for all 3 Layout templates A, B and C. In the
case of Layouts A and B, PayPal will auto-detect if the checkout page is being viewed from a
supported mobile browser and will redirect to the mobile optimized checkout page. For Layout
C, PayPal does not automatically redirect mobile users to a mobile optimized flow. The reason
is that if PayPal automatically showed a mobile optimized embedded template, within a
merchant web page that may not be mobile optimized, this can create unexpected and
undesirable results. To display the mobile checkout page for Layout C, you must detect the
Configuring Hosted Checkout Pages
Hosted Pages and Mobile Browsers
3
46 07 February 2013 Gateway Developer Guide and Reference
supported mobile browser and then explicitly pass the form post parameter:
TEMPLATE=MOBILE.
The TEMPLATE form post parameter
The mobile checkout pages are identical for all Layout templates: Layouts A, B and the mobile
version of Layout C. Additionally, appearance customizations that you set in PayPal Manager or
submit as form post parameters are not applied to the mobile pages. The figures below show
the mobile optimized page flow for a PayPal payment and for a credit card payment:
Mobile page flow for a PayPal payment
Layout TEMPLATE parameter value Behavior on a Mobile Device
Layout A TEMPLATE=TEMPLATEA Auto-redirects to mobile optimized
page
Layout B TEMPLATE=TEMPLATEB Auto-redirects to mobile optimized
page
Layout C TEMPLATE=MINLAYOUT (default)
TEMPLATE=MOBILE
Use TEMPLATE=MINLAYOUT for
your general online checkout. If
you have a mobile optimized
experience, explicitly pass
TEMPLATE=MOBILE instead to
show the mobile optimized page.
Gateway Developer Guide and Reference 07 February 2013 47
Configuring Hosted Checkout Pages
Silent Posts 3
Mobile page flow for a credit card payment
Silent Posts
Silent Post ensures that the transaction data is passed back to your website when a transaction
is completed. The Silent Post feature uses the HTML Post method to return data to your server
for both approved and declined trasactions. This occurs even if a customer closes the browser
before returning to your site, or if the PayPal-hosted payment confirmation page is disabled.
Silent Post data is sent to your server at the same time as when a payment confirmation page is
displayed or as soon as a transaction is declined.
This feature is configured through https://manager.paypal.com:
-Go to Service Settings, then from the Hosted Checkout Pages section select Setup
-On the Setup page, set Use Silent Post to Yes. Then enter the Silent Post URL on your
server.
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
Void 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 servers 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
Configuring Hosted Checkout Pages
Passing Other Data to Your Server Using Post or Silent Post
3
48 07 February 2013 Gateway Developer Guide and Reference
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.
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).
Passing Other Data to Your Server Using Post or Silent Post
The USER1 through USER10 Payflow parameters are ten optional string type parameters
intended to store your temporary data, such as variables, session IDs, order numbers, and so
on. These parameters enable you to pass internal information to your server using the Post or
Silent Post feature.
NOTE:USER1 through USER10 are not displayed to the customer and are not stored in the
PayPal transaction database.
Gateway Developer Guide and Reference 07 February 2013 49
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 49.
-“Activating Your Payflow Gateway Account” on page 50.
-“Host URL Addresses” on page 50
NOTE:Each SDK includes full API documentation.
IMPORTANT:The Payflow SDK is available as a .NET or Java library. Using these SDKs is
recommended to simplify integration. Alternately you can build your own
API by posting transactions directly to the Gateway servers using HTTPS.
See “Posting Transactions Directly Without the Payflow SDK” on page 208
for more information.
Any reference to Payflow SDK or the 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
4
50 07 February 2013 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
NOTE:If you are using an older version of the SDK, you will notice that the live and
testing URLs have changed. Be sure to use the URLs mentioned above and remove
the “/transaction” from the end of the URL.
Testing Your PayPal Payments Advanced and PayPal Payments Pro Integration
If you have a PayPal Payments Advanced or a PayPal Payments Pro account and you would
like to use the testing URL to test your integration, you will first need a PayPal Sandbox test
account. If you do not have a Sandbox account, go to http://developer.paypal.com and follow the
instructions to create this account.
You will need to enter your Sandbox account information on the Setup page of PayPal
Manager http://manager.paypal.com ( Service Settings -> Hosted Checkout Pages -> Setup).
Fill-in the PayPal Sandbox Email Address field and click Save. You can now test your
Payflow Gateway integration against the testing URL: https://pilot-
payflowpro.paypal.com.
Passing Information to and Receiving Information from the Hosted Pages
If you would like to pass information to or receive information from the PayPal Hosted
Checkout Pages, use one of the following URLs:
-For live transactions, use https://payflowlink.paypal.com
-For testing purposes, use https://pilot-payflowlink.paypal.com
NOTE:You no longer need to use the MODE parameter when passing a test secure token.
Instead, post your form parameters to the testing Payflow Link URL. The MODE
parameter will be deprecated in the future.
Gateway Developer Guide and Reference 07 February 2013 51
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 51
-“Payflow Connection Parameters” on page 52
-“User Parameter Data” on page 53
-“Sale Transaction Example” on page 54
-“Formatting Payflow Gateway Transactions” on page 54
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
5
52 07 February 2013 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.
-If you duplicate a parameter in your NVP string, the last item will always be the one used
and the others will be discarded.
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.
Gateway Developer Guide and Reference 07 February 2013 53
Sending a Simple Transaction to the Server
User Parameter Data 5
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.
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
5
54 07 February 2013 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 buyers 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 or see Submitting Credit Card Transactions.
Gateway Developer Guide and Reference 07 February 2013 55
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.
NOTE:Some of the transaction types and features described in this chapter are not supported
by all processors. Be sure to check with your processor for information on the specific
functionality that is supported.
-“Obtaining an Internet Merchant Account” on page 56
-“About Credit Card Processing” on page 56
-“Credit Card Features” on page 57
-“Planning Your Gateway Integration” on page 57
-“Core Credit Card Parameters” on page 59
-“Submitting Account Verifications” on page 62
-“Submitting Authorization/Delayed Capture Transactions” on page 63
-“Submitting Balance Inquiry Transactions” on page 64
-“Submitting Card Present (SWIPE) Transactions” on page 65
-“Submitting Credit Transactions” on page 67
-“Submitting Inquiry Transactions” on page 69
-“Submitting Partial Authorizations” on page 72
-“Submitting Purchasing Card Transactions” on page 73
-“Submitting Reference Transactions (Tokenization)” on page 74
-“Submitting Sale Transactions” on page 77
-“Submitting Soft Merchant Information” on page 78
-“Submitting Voice Authorization Transactions” on page 80
-“Submitting Void Transactions” on page 80
-“Using Address Verification Service” on page 82
-“Using Card Security Code” on page 83
Submitting Credit Card Transactions
Obtaining an Internet Merchant Account
6
56 07 February 2013 Gateway Developer Guide and Reference
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
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 cardholders 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 cardholders 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.
Gateway Developer Guide and Reference 07 February 2013 57
Submitting Credit Card Transactions
Credit Card Features 6
Credit Card Features
The Payflow SDK supports the following transaction types for credit card processing:
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
Transaction Type Billable
Authorization Yes
Account Verification No
Balance Inquiry No
Credit Yes
Delayed Capture No
Inquiry No
Sale Yes
Voice Authorization Yes
Vo i d Ye s
Submitting Credit Card Transactions
Planning Your Gateway Integration
6
58 07 February 2013 Gateway Developer Guide and Reference
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,
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).
Gateway Developer Guide and Reference 07 February 2013 59
Submitting Credit Card Transactions
Core Credit Card Parameters 6
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.
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
Submitting Credit Card Transactions
Core Credit Card Parameters
6
60 07 February 2013 Gateway Developer Guide and Reference
EXPDATE (Required) Expiration date of the credit card. For example, 1215 represents
December 2015.
Limitations: mmyy format
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 buyers 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 Managers 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
Parameter Description
Gateway Developer Guide and Reference 07 February 2013 61
Submitting Credit Card Transactions
Core Credit Card Parameters 6
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 51.
NOTE:SWIPE (card-present transactions) are not supported by the PayPal processor.
Limitations: Alphanumeric and special characters
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: 2-character string (Varies depending on processor: 2 to 45 characters).
BILLTOZIP (Optional) Account holders 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.
Parameter Description
Submitting Credit Card Transactions
Submitting Account Verifications
6
62 07 February 2013 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 cardholders 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 74.
Required Account Verification Parameters
To perform account verification, pass the following parameters:
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: 2-character string (Varies depending on processor: 2 to 45 characters).
SHIPTOZIP (Optional) Ship-to postal code.
Limitations: 10-character string.
SHIPTOCOUNTRY (Optional) Ship-to country.
Limitations: 3-character country code.
Parameter Description
TRXTYPE (Required) Set to A.
Limitations: 1 alphanumeric character.
Parameter Description
Gateway Developer Guide and Reference 07 February 2013 63
Submitting Credit Card Transactions
Submitting Authorization/Delayed Capture Transactions 6
Example Account Verification String
The following is an example of account verification:
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 cardholders open-to-buy
limit, lowering the cardholders 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.
AMT (Required) Set to 0.
VERBOSITY (Required) Set to HIGH to obtain information about a partial authorization in the
response.
Parameter Description
Submitting Credit Card Transactions
Submitting Balance Inquiry Transactions
6
64 07 February 2013 Gateway Developer Guide and Reference
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 77. 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 74.
NOTE:You are allowed to perform one delayed capture transaction per authorization
transaction.
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.
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.
Gateway Developer Guide and Reference 07 February 2013 65
Submitting Credit Card Transactions
Submitting Card Present (SWIPE) Transactions 6
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:
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.
WorldPay
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
6
66 07 February 2013 Gateway Developer Guide and Reference
-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.
Processing Platforms Supporting Card-Present Transactions
The following processing platforms support card-present transactions.
American Express
American Express APAC
Elavon
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
Van t iv
WorldPay
Gateway Developer Guide and Reference 07 February 2013 67
Submitting Credit Card Transactions
Submitting Credit Transactions 6
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 51. The length tag in the following example
is [40].
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
Submitting Credit Card Transactions
Submitting Credit Transactions
6
68 07 February 2013 Gateway Developer Guide and Reference
transactions. To submit a credit transaction when non-referenced credits are not allowed, pass
the following parameter:
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.
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
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 07 February 2013 69
Submitting Credit Card Transactions
Submitting Inquiry Transactions 6
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.
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.
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
6
70 07 February 2013 Gateway Developer Guide and Reference
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:
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
Gateway Developer Guide and Reference 07 February 2013 71
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.
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
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
6
72 07 February 2013 Gateway Developer Guide and Reference
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.
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.
Gateway Developer Guide and Reference 07 February 2013 73
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.
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.
Submitting Credit Card Transactions
Submitting Reference Transactions (Tokenization)
6
74 07 February 2013 Gateway Developer Guide and Reference
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 3 Transactions” on page 151.
NOTE:The PayPal processor does not support purchasing card transactions.
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. 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.
Gateway Developer Guide and Reference 07 February 2013 75
Submitting Credit Card Transactions
Submitting Reference Transactions (Tokenization) 6
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
-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:
ACCTTYPE BILLTOSTREET
ACCT BILLTOCITY
EXPDATE BILLTOSTATE
BILLTOFIRSTNAME BILLTOZIP
BILLTOMIDDLENAME BILLTOCOUNTRY
BILLTOLASTNAME SWIPE
Submitting Credit Card Transactions
Submitting Reference Transactions (Tokenization)
6
76 07 February 2013 Gateway Developer Guide and Reference
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.
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
Gateway Developer Guide and Reference 07 February 2013 77
Submitting Credit Card Transactions
Submitting Sale Transactions 6
-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
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 62.
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 63. 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
Submitting Credit Card Transactions
Submitting Soft Merchant Information
6
78 07 February 2013 Gateway Developer Guide and Reference
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.
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 customers 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 65
-“Using Card Security Code” on page 83
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 buyers 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 Hikers 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 Hikers 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 Hikers Duds in San Jose.
Gateway Developer Guide and Reference 07 February 2013 79
Submitting Credit Card Transactions
Submitting Soft Merchant Information 6
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.
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
holders 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 Credit Card Transactions
Submitting Voice Authorization Transactions
6
80 07 February 2013 Gateway Developer Guide and Reference
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.
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 customers statement.
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 07 February 2013 81
Submitting Credit Card Transactions
Submitting Void Transactions 6
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.
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
customers 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
Submitting Credit Card Transactions
Using Address Verification Service
6
82 07 February 2013 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 cardholders bank. The response includes values for AVSADDR and
AVSZIP: Y, N, or X for the match status of the customers street address and zip code.
Y= match, N=nomatch, X= cardholders 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 processors 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
SHIPTOFIRSTNAME SHIPTOMIDDLENAME SHIPTOLASTNAME SHIPTOSTATE
SHIPTOSTREET SHIPTOZIP BILLTOSTATE BILLTOSTREET
SWIPE TAXAMT BILLTOPHONENUM TAXEXEMPT
BILLTOZIP
Gateway Developer Guide and Reference 07 February 2013 83
Submitting Credit Card Transactions
Using Card Security Code 6
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
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
buyers 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
6
84 07 February 2013 Gateway Developer Guide and Reference
Gateway Developer Guide and Reference 07 February 2013 85
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 50.
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
7
86 07 February 2013 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 07 February 2013 87
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
more
13 Referral Use the AMOUNT 1013
Processing Platform RESULT Values Available for Testing
Testing Transactions
Processors Other Than PayPal
7
88 07 February 2013 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 07 February 2013 89
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
X
RESULT value Definition How to test using Payflow Gateway
Testing Transactions
PayPal Processor
7
90 07 February 2013 Gateway Developer Guide and Reference
Testing Card Security Code
If you submit a value for the card security code, the cardholders 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 07 February 2013 91
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
7
92 07 February 2013 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 07 February 2013 93
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
7
94 07 February 2013 Gateway Developer Guide and Reference
Gateway Developer Guide and Reference 07 February 2013 95
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
8
96 07 February 2013 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 07 February 2013 97
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
8
98 07 February 2013 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 = Diners 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=2ORDERID 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 07 February 2013 99
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 AVS
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
XX
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
8
100 07 February 2013 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
X No Response X
Gateway Developer Guide and Reference 07 February 2013 101
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:
-VADE0B248932
All other X
PayPal Processor CVV2 Code
PayPal Processor Code
Description PROCVV2MATCH
Transaction Responses
RESULT Values and RESPMSG Text
8
102 07 February 2013 Gateway Developer Guide and Reference
-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 07 February 2013 103
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
8
104 07 February 2013 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 07 February 2013 105
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
8
106 07 February 2013 Gateway Developer Guide and Reference
112 Failed AVS check. Address and zip code do not match. An authorization may still exist
on the cardholders 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
cardholders account.
115 System busy, try again later
116 Failed to lock terminal number. Please try again later. 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 07 February 2013 107
Transaction Responses
RESULT Values and RESPMSG Text 8
150 Issuing bank timed out
PayPal Australia 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
160 Secure Token already been used. Indicates that the secure token has expired due to
either a successful transaction or the token has been used three times while trying to
successfully process a transaction. You must generate a new secure token.
161 Transaction using secure token is already in progress. This could occur if a
customer hits the submit button two or more times before the transaction completed.
162 Secure Token Expired. The time limit of 20 minutes has expired and the token can no
longer be used.
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
RESULT RESPMSG and Explanation
Transaction Responses
RESULT Values and RESPMSG Text
8
108 07 February 2013 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 49. 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.
1023 Buyer Authentication Service — merchant status for 3D secure is invalid
1041 Buyer Authentication Service — Validate Authentication failed: missing or invalid
PARES
1042 Buyer Authentication Service — Validate Authentication failed: PARES format is
invalid
1043 Buyer Authentication Service — Validate Authentication failed: Cannot find
successful Verify Enrollment
1044 Buyer Authentication Service — Validate Authentication failed: Signature
validation failed for PARES
1045 Buyer Authentication Service — Validate Authentication failed: Mismatched or
invalid amount in PARES
1046 Buyer Authentication Service — Validate Authentication failed: Mismatched or
invalid acquirer in PARES
1047 Buyer Authentication Service — Validate Authentication failed: Mismatched or
invalid Merchant ID in PARES
1048 Buyer Authentication Service — Validate Authentication failed: Mismatched or
invalid card number in PARES
1049 Buyer Authentication Service — Validate Authentication failed: Mismatched or
invalid currency code in PARES
1050 Buyer Authentication Service — Validate Authentication failed: Mismatched or
invalid XID in PARES
1051 Buyer Authentication Service — Validate Authentication failed: Mismatched or
invalid order date in PARES
1052 Buyer Authentication Service — Validate Authentication failed: This PARES was
already validated for a previous Validate Authentication transaction
RESULT RESPMSG and Explanation
Gateway Developer Guide and Reference 07 February 2013 109
Transaction Responses
RESULT Values and RESPMSG Text 8
RESULT Description
-1 Failed to connect to host
-2 Failed to resolve hostname
-5 Failed to initialize SSL context
-6 Parameter list format error: & in name
-7 Parameter list format error: invalid [ ] name length clause
-8 SSL failed to connect to host
-9 SSL read failed
-10 SSL write failed
-11 Proxy authorization failed
-12 Timeout waiting for response
-13 Select failure
-14 Too many connections
-15 Failed to set socket options
-20 Proxy read failed
-21 Proxy write failed
-22 Failed to 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
Transaction Responses
RESULT Values and RESPMSG Text
8
110 07 February 2013 Gateway Developer Guide and Reference
-103 Context initialization failed
-104 Unexpected transaction state
-105 Invalid name value pair request
-106 Invalid response format
-107 This XMLPay version is not supported
-108 The server certificate chain did not validate
-109 Unable to do logging
-111 The following error occurred while initializing from message file: <Details of the error message>
-113 Unable to round and truncate the currency value simultaneously
RESULT Description
Gateway Developer Guide and Reference 07 February 2013 111
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 111
-“Elavon Additional Credit Card Parameters” on page 117
-“First Data Merchant Services Nashville, Additional Credit Card Parameters” on page 118
-“First Data Merchant Services North, Additional Credit Card Parameters” on page 118
-“Heartland, Additional Credit Card Parameters” on page 119
-“Litle Additional Credit Card Parameters” on page 119
-“Merchant e-Solutions, Additional Credit Card Parameters” on page 121
-“Paymentech Salem (New Hampshire) Additional Credit Card Parameters for American
Express” on page 121
-“PayPal Credit Card Transaction Request Parameters” on page 123
-“SecureNet Additional Credit Card Parameters for American Express” on page 128
-“Vantiv Additional Credit Card Parameters” on page 133
-“WorldPay Additional Credit Card Parameters” on page 135
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
A
112 07 February 2013 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 holders email address.
Character length and limitations: 60 alphanumeric characters
BILLTOPHONENUM (Optional) Account holders 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 holders 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 07 February 2013 113
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 holders street address (number and street name).
Character length and limitations: 20 characters
BILLTOZIP (Optional) Account holders 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 holders 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
A
114 07 February 2013 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 merchants 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 sellers 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-members 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 07 February 2013 115
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
A
116 07 February 2013 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 07 February 2013 117
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 Managers 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
A
118 07 February 2013 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 holders
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 holders
statement.
Character length and limitations: 25 alphanumeric characters
Gateway Developer Guide and Reference 07 February 2013 119
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 holders 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 holders 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 holders 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
A
120 07 February 2013 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 merchants 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
holders 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 holders 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