Gateway Developer Guide and Reference

PayPal Payments Advanced PayPal Payments Pro Payflow Pro Payflow Link

Last updated: 19 July 2013

Gateway Developer Guide and Reference Document Number: 200045.en_US-201307

1999 - 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., Socit 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.

Content

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

Summary of the Gateway Checkout Solutions . . . . . . . . . . . . . . . . . . . . . 23 Gateway Product Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

About the Gateway Checkout Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

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

Gateway Developer Guide and Reference

19 July 2013

Content

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

Using Special Characters In Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Name-Value Parameter Syntax Guidelines . . . . . . . . . . . . . . . . . . . . . . . 52 Do Not URL Encode Name-Value Parameter Data . . . . . . . . . . . . . . . . . . . 52

About Name-Value Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

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

19 July 2013

Gateway Developer Guide and Reference

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 Submitting Balance Inquiry Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Processing Platforms Supporting Balance Inquiry Transactions . . . . . . . . . . . . 64 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Submitting Credit (Refund) Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Required Credit Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . 67 Submitting Inquiry Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 When To Use an Inquiry Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Required Parameters When Using the PNREF . . . . . . . . . . . . . . . . . . . . . 69 Inquiry Transaction Parameter String Using the PNREF . . . . . . . . . . . . . . . . 69 Required Parameters When Using the CUSTREF . . . . . . . . . . . . . . . . . . . 70 Inquiry Transaction Parameter String Using the CUSTREF . . . . . . . . . . . . . . . 70 Required Parameters When Using the Secure Token . . . . . . . . . . . . . . . . . . 70 Inquiry Parameter String Using the Secure Token . . . . . . . . . . . . . . . . . . . . 71 Submitting Partial Authorizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 When To Use Partial Authorizations . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Required Partial Authorization Parameters . . . . . . . . . . . . . . . . . . . . . . . 72 Example Partial Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Submitting Purchasing Card Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Submitting Reference Transactions (Tokenization) . . . . . . . . . . . . . . . . . . . . . 73 When To Use a Reference Transaction . . . . . . . . . . . . . . . . . . . . . . . . . 73 Transaction Types That Can Be Used As the Original Transaction . . . . . . . . . . . 74 Fields Copied From Reference Transactions . . . . . . . . . . . . . . . . . . . . . . 74 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 Additional Parameters For Sale Transactions . . . . . . . . . . . . . . . . . . . . . . 77

Gateway Developer Guide and Reference

19 July 2013

Content

Typical Sale Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . . 77 Submitting Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 About Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Ways to Send Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . 78 Submitting Voice Authorization Transactions . . . . . . . . . . . . . . . . . . . . . . . . 79 When To Use a Voice Authorization Transaction . . . . . . . . . . . . . . . . . . . . 79 Required Voice Authorization Transaction Parameters . . . . . . . . . . . . . . . . . 80 Submitting Void Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 When To Use a Void Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Required Void Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 80 Fields Copied From the Original Transaction Into the Void Transaction. . . . . . . . . 81 Example Void Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . 81 Using Address Verification Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Example Address Verification Service Parameter String . . . . . . . . . . . . . . . . 82 Using Card Security Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Information for the PayPal Acquirer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Countries and Regions Supported by PayPal . . . . . . . . . . . . . . . . . . . . . . 83 PayPal Currency Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

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 Testing the Litle Automatic Account Updater Feature . . . . . . . . . . . . . . . . . . 90 PayPal Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Credit Card Numbers for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Result Values Based On Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Chapter 8

Transaction Responses . . . . . . . . . . . . . . . . . . . 95

Credit Card Transaction Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Address Verification Service Responses From PayPal . . . . . . . . . . . . . . . . . . . 99 Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100 Normalized Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . .100 BALAMT Response and Stored Value Cards . . . . . . . . . . . . . . . . . . . . . . . .100 American Express Stored Value Card Example . . . . . . . . . . . . . . . . . . . . .101 6

19 July 2013

Gateway Developer Guide and Reference

Content

PNREF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101 RESULT Values and RESPMSG Text . . . . . . . . . . . . . . . . . . . . . . . . . . . .101 RESULT Values For Communications Errors . . . . . . . . . . . . . . . . . . . . . .108 Processor-specific Response Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .109 Litle Response Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Appendix A Processors Requiring Additional Transaction Parameters 113

American Express Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . 113 Retail Transaction Advice Addendum (for SWIPE transactions) . . . . . . . . . . . . 113 Internet Transaction Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Address Verification Service Parameters . . . . . . . . . . . . . . . . . . . . . . . . 115 Location Transaction Advice Addendum Parameters . . . . . . . . . . . . . . . . . . 115 Transaction Advice Detail Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . 117 Airline Passenger Data Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 American Express Other Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Elavon Additional Credit Card Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . 119 First Data Merchant Services Nashville, Additional Credit Card Parameters . . . . . . . .120 First Data Merchant Services North, Additional Credit Card Parameters . . . . . . . . . .120 Heartland, Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . .121 Litle Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .121 Merchant e-Solutions, Additional Credit Card Parameters. . . . . . . . . . . . . . . . . .123 Paymentech Salem (New Hampshire) Additional Credit Card Parameters for American Express . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123 Internet Transaction Data Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .123 AVS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124 Additional Credit Card Parameters for M Record . . . . . . . . . . . . . . . . . . . .125 PayPal Credit Card Transaction Request Parameters . . . . . . . . . . . . . . . . . . . .125 SecureNet Additional Credit Card Parameters for American Express . . . . . . . . . . . .130 Retail Transaction Advice Addendum (for SWIPE transactions) . . . . . . . . . . . .130 Internet Transaction Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130 AVS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131 Location Transaction Advice Addendum Parameters . . . . . . . . . . . . . . . . . .132 Transaction Advice Detail Parameters. . . . . . . . . . . . . . . . . . . . . . . . . .133 Airline Passenger Data Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .133 Other Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135 Vantiv Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .135 Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .135 Soft Merchant Descriptor Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .135

Gateway Developer Guide and Reference

19 July 2013

Content

WorldPay Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . .137

Appendix B TeleCheck Electronic Check Processing . . . . . . . . . 139

TeleCheck NFTF Overview of Services . . . . . . . . . . . . . . . . . . . . . . . . . . .139 TeleCheck NFTF Processing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . .139 NFTF Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139 NFTF Processing Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . .141 NFTF Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141 TeleCheck Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142 Required TeleCheck Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .143 Testing TeleCheck Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145 Example Test Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145 Preparing for TeleCheck Production Transactions . . . . . . . . . . . . . . . . . . . . . .146 Responses to TeleCheck Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . .146 Transaction Responses Common to All Tender Types . . . . . . . . . . . . . . . . .146 Response Code Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147 Sale Response Code Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147 Adjustment Code Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148 Response Codes For Status Response Packets . . . . . . . . . . . . . . . . . . . .148 TeleCheck Authorization Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . .149 Authorization Sales Consent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149 Authorization Sales Decline/Error . . . . . . . . . . . . . . . . . . . . . . . . . . .152

Appendix C Submitting Purchasing Card Level 2 and 3 Transactions . 153

About Purchasing Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153 About Program Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153 Accepted BIN Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154 About American Express Purchasing Card Transactions . . . . . . . . . . . . . . . . . .154 Supported Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154 Avoiding Downgrade. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155 Submitting Successful Level 3 Transactions . . . . . . . . . . . . . . . . . . . . . .155 Edit Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155 Accepted BIN Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156 American Express Purchasing Card Transaction Processing . . . . . . . . . . . . . . . .156 American Express Level 2 Parameters for American Express . . . . . . . . . . . . .156 Example American Express Level 2 Transaction Parameter String . . . . . . . . . . .159 American Express Level 3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . .159 Example American Express Level 3 Transaction Parameter String . . . . . . . . . . .161

19 July 2013

Gateway Developer Guide and Reference

Content

Elavon (Formerly Nova) Purchasing Card Transaction Processing . . . . . . . . . . . . .162 Elavon Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162 Elavon Additional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162 Example Elavon Level 2 Transaction Parameter String . . . . . . . . . . . . . . . . .163 First Data Merchant Services (FDMS) Nashville Purchasing Card Transaction Processing.163 FDMS Nashville Commercial Card Parameters . . . . . . . . . . . . . . . . . . . . .163 First Data Merchant Services (FDMS) North Purchasing Card Transaction Processing . .164 FDMS North Purchasing Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .164 FDMS North Purchasing Card Line Item Parameters . . . . . . . . . . . . . . . . . .165 First Data Merchant Services South (FDMS) Purchasing Card Transaction Processing . .165 FDMS South Level 2 and Level 3 Purchasing Card Parameters . . . . . . . . . . . .166 FDMS South Line Item Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .167 Example FDMS South Purchasing Card Level 2 and 3 Parameter String . . . . . . . .168 Example FDMS South Line Item Parameter String . . . . . . . . . . . . . . . . . . .168 Global Payments - Central Purchasing Card Transaction Processing . . . . . . . . . . . .169 Global Payments - Central Level 2 Parameters . . . . . . . . . . . . . . . . . . . . .169 Global Payments - East Purchasing Card Transaction Processing . . . . . . . . . . . . .169 Global Payments - East Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . .169 Example Global Payments - East Level 2 Visa or MasterCard Transaction Parameter String 170 Heartland Purchasing Card Transaction Processing. . . . . . . . . . . . . . . . . . . . .170 Heartland Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170 Heartland Level 3 MasterCard Parameters . . . . . . . . . . . . . . . . . . . . . . .171 Heartland Level 3 Visa Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .173 Litle Purchasing Card Transaction Processing. . . . . . . . . . . . . . . . . . . . . . . .176 Litle Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176 Litle Level 3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177 Merchant e-Solutions Purchasing Card Transaction Processing . . . . . . . . . . . . . .179 Merchant e-Solutions Level 2 Parameters. . . . . . . . . . . . . . . . . . . . . . . .179 Merchant e-Solutions Level 3 MasterCard Parameters . . . . . . . . . . . . . . . . .179 Merchant e-Solutions Level 3 Visa Parameters . . . . . . . . . . . . . . . . . . . . .182 Paymentech Salem (New Hampshire) Purchasing Card Transaction Processing . . . . . .184 Paymentech Salem (New Hampshire) Level 2 Parameters for American Express . . .184 Paymentech Salem (New Hampshire) Level 3 Purchasing Card Parameters. . . . . .187 Paymentech Tampa Level 2 Purchasing Card Transaction Processing . . . . . . . . . . .190 Paymentech Tampa Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . .191 Example Paymentech Tampa Level 2 Visa and MasterCard Transaction Parameter String 191 SecureNet Purchasing Card Transaction Processing . . . . . . . . . . . . . . . . . . . .191 SecureNet Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191 9

Gateway Developer Guide and Reference

19 July 2013

Content

SecureNet Level 3 MasterCard Parameters . . . . . . . . . . . . . . . . . . . . . . .192 SecureNet Acquiring Solutions Level 3 Visa Parameters . . . . . . . . . . . . . . . .194 TSYS Acquiring Solutions Purchasing Card Transaction Processing . . . . . . . . . . . .197 TSYS Acquiring Solutions Level 2 Parameters . . . . . . . . . . . . . . . . . . . . .197 TSYS Acquiring Solutions Level 3 MasterCard Parameters. . . . . . . . . . . . . . .197 TSYS Acquiring Solutions Level 3 Visa Parameters. . . . . . . . . . . . . . . . . . .200 Vantiv Purchasing Card Transaction Processing . . . . . . . . . . . . . . . . . . . . . .203 Vantiv Purchasing Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .203 Vantiv Purchasing Card Line Item Parameters . . . . . . . . . . . . . . . . . . . . .203 WorldPay Purchasing Cards Transaction Processing . . . . . . . . . . . . . . . . . . . .204 WorldPay Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204 WorldPay Level 3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206

Appendix D Payflow Header Parameters . . . . . . . . . . . . . . . . 209

Sending Requests Directly to PayPal Bypassing Payflow . . . . . . . . . . . . . . . . . .209 Posting Transactions Directly Without the Payflow SDK. . . . . . . . . . . . . . . . . . .210 The Payflow Message Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . .210 Payflow Message Protocol Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 Transaction Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .213 Integrator-Provided Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .214

Appendix E VERBOSITY: Processor-Specific Transaction Results Appendix F

. . 217

ISO Country Codes . . . . . . . . . . . . . . . . . . . . 219

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

MasterCard Country Codes for FDMS South Only . . . . . . . . . . . . . . . . . . . . .221 Visa Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228 Units of Measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235

Appendix I

Additional Processor Information . . . . . . . . . . . . . 243

Moneris Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243

Appendix J

Payflow Link Migration . . . . . . . . . . . . . . . . . . 245

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

10

19 July 2013

Gateway Developer Guide and Reference

Content

Appendix 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

Gateway Developer Guide and Reference

19 July 2013

11

Content

12

19 July 2013

Gateway Developer Guide and Reference

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 Classic APIs - 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://developers.paypal.com

Intended Audience
This guide provides Gateway payments solutions to readers who:

Are web or application developers Have a background in payments services

Gateway Developer Guide and Reference

19 July 2013

13

Intended Audience

Who Should Use This Document

This comprehensive developer guide includes integration information for multiple Gateway solutions.
NOT E :

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

14

19 July 2013

Gateway Developer Guide and Reference

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)

Gateway Developer Guide and Reference

19 July 2013

15

Intended Audience

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)

16

19 July 2013

Gateway Developer Guide and Reference

Revision History

Revision History
Revision History for the Gateway Developer Guide and Reference:
Date 19 Jul 2013 11 Jul 2013 Description Removed the ACCTTYPE parameter from this guide. Maintenance release. Added a new section on Processor-specific Response Parameters, which includes Litle Response Parameters and information on the Litle Automatic Account Updater feature. Added information on Testing the Litle Automatic Account Updater Feature. Added information on Submitting Credit (Refund) Transactions for the PayPal processor. Added the PAYMENTADVICECODE field to Credit Card Transaction Responses. Added a note on problems with using legacy Payflow Link parameters with the Secure Token. Updated the support contact information for enabling PayPal processor line-item support in the PayPal Credit Card Transaction Request Parameters table. Added a Level 3 Required Parameters table to TSYS Acquiring Solutions Level 3 Visa Parameters. Added information on Reference Authorizations and Sales specific to the PayPal processor in the Example Reference Transaction.section. Updated URL paths. Updated the description of the Drivers Licencse - DL field in Required TeleCheck Parameters. Updated the description of the Drivers Licencse - DL field in Required TeleCheck Parameters.

15 Jun 2013

25 Apr 2013 22 Feb 2013

Gateway Developer Guide and Reference

19 July 2013

17

Revision History

Date 28 Jan 2013

Description 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 parameters BILLTOSTATE and SHIPTTOSTATE 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 Parameters. Updated the description of the Drivers Licencse - DL field in Required TeleCheck Parameters. 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. 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. Added the Payflow Gateway MagTek Parameters Appendix. Added a list of Setup and Customize parameters in the section on Using a Secure Token to Pass Hosted Pages Customization Parameters. These parameters override PayPal Manager settings for Hosted Pages. Briefly explained the differences between Submitting Credit (Refund) Transactions and Submitting Void Transactions.

28 Dec 2012 11 Dec 2012

04 Oct 2012

29 Aug 2012 31 July 2012

18

19 July 2013

Gateway Developer Guide and Reference

Revision History

Date

Description 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 16 July 2012

Added the Bill Me Later feature to the Gateway Product Details section. Updated the value of the required column for the BILLTOCITY, BILLTOSTATE & BILLTOCOUNTRY parameters in PayPal Credit Card Transaction Request Parameterstable. Added the Who Should Use This Document section to the Preface. In the Integrating the Secure Token Without the Hosted Checkout Pages: Transparent Redirect section, corrected the value of SILENTTRAN to True Added Silent Posts section to the Hosted Checkout Pages chapter. Removed the legacy paramater CORPCOUNTRYfrom ISO Country Codes.

June 2012

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

April 2012

Added new transaction type: Balance Inquiry(TRXTYPE=B) can be used to obtain the balance of a pre-paid card. Updated TeleCheck chapter: Updated MICR values in Testing TeleCheck Transactions section Added TeleCheck Adjustment Response Code Values table

Gateway Developer Guide and Reference

19 July 2013

19

Revision History

Date

Description Updated parameters and examples: Added a description for the 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 the Litle parameters STREET2,STREET3 to BILLTOSTREET2, BILLTOSTREET3. Corrected the 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.

20

19 July 2013

Gateway Developer Guide and Reference

Revision History

Date January 2012 (cont.)

Description Added request parameters: 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 parameters: DUPLICATE (response) EXTRMSG (response)

Gateway Developer Guide and Reference

19 July 2013

21

Revision History

Date January 2012 (cont.)

Description Added concepts: Gateway Product Solutions - PayPal Payments Advanced, PayPal Payments Pro, Payflow Pro, Payflow Link Transaction Flow Transparent Redirect First publication.

February 2011

22

19 July 2013

Gateway Developer Guide and Reference

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

Gateway Developer Guide and Reference

19 July 2013

23

Introducing the Gateway Checkout Solutions

About the Gateway Checkout Solutions

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

NOT E :

Gateway Product Details

The table below compares how the Gateway checkout solutions support payment processing features.

Feature Hosted checkout page (including an iFrame version) PayPal payments Bill Me Later payments (Available to US merchants only on Hosted checkout pages.) PayPal branding on full page templates Transparent Redirect Supports PayPal as a processor and an acquirer Credit and debit cards Level 2 and Level 3 purchase cards TeleCheck (guaranteed electronic checks) ACH (electronic checks) Virtual Terminal support, including card-present data passage Virtual Terminal API

PayPal Payments Advanced Payflow Link Yes Included Included

PayPal Payments Pro Payflow Pro Yes Optional Optional

Yes No Yes Yes Yes No No Yes Payflow Link only Limited access (Authorization and Sale API calls not permitted)

Optional Yes Yes Yes Yes Yes Yes Yes Yes Full access

24

19 July 2013

Gateway Developer Guide and Reference

Introducing the Gateway Checkout Solutions

About the Gateway Transaction Flow

Feature Reference transactions (Tokenization) Secure token to preset hosted checkout page Reporting APIs Desktop integration Recurring billing Basic fraud protection Advanced fraud protection Partner/channel distribution support (Partner Manager, registration, XML registration) resale and referral

PayPal Payments Advanced Payflow Link Yes Yes Yes Yes Yes Yes Yes Yes

PayPal Payments Pro Payflow Pro Yes Yes Yes Yes Yes Yes Yes Yes

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:
Gateway Developer Guide and Reference 19 July 2013

25

Introducing the Gateway Checkout Solutions

About Security

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 customer's statement or describe line items in greater detail. Be sure to check for your processor's 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.
NOT E :

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.
NOT E :

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.

26

19 July 2013

Gateway Developer Guide and Reference

Introducing the Gateway Checkout Solutions

About Security

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 customer's 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.
NOT E :

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.

Gateway Developer Guide and Reference

19 July 2013

27

Introducing the Gateway Checkout Solutions

Processing Platforms Supporting Card-Present Transactions

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.
NOT E :

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

28

19 July 2013

Gateway Developer Guide and Reference

Introducing the Gateway Checkout Solutions

Supported Payment Types

Moneris Solutions Paymentech Salem Paymentech Tampa PayPal SecureNet TeleCheck TSYS Acquiring Solutions Vantiv WorldPay

Supported Payment Types

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.

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.

Gateway Developer Guide and Reference

19 July 2013

29

Introducing the Gateway Checkout Solutions

Recurring Billing Service

Recurring Billing Service

The Recurring Billing Service is a scheduled payment solution that enables you to automatically bill your customers at regular intervalsfor 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 Fraud Protection Services Users 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.

30

19 July 2013

Gateway Developer Guide and Reference

Secure Token

This section describes the secure token. Secure Token on page 31 Integrating the Secure Token With the Hosted Checkout Pages on page 32 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

IM PORT AN T :

Use only the Payflow parameters described in this guide with the Secure Token. If you are using the legacy Payflow Link HTML input tag integration, refer to the Payflow Link Users Guide for information on legacy Payflow Link features supported by your integration.

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.
NOT E :

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.
NOT E :

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.

Gateway Developer Guide and Reference

19 July 2013

31

Secure Token
Integrating the Secure Token With the Hosted Checkout Pages

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.
NOT E :

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.

32

19 July 2013

Gateway Developer Guide and Reference

Secure Token
Secure Token Errors
NOT E :

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 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.
NOT E :

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.

Gateway Developer Guide and Reference

19 July 2013

33

Secure Token
Posting To the Hosted Checkout Page

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.
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. 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. Secure Token Expired. The time limit of 20 minutes has expired and the token can no longer be used.

161 162

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.

34

19 July 2013

Gateway Developer Guide and Reference

Secure Token
Posting 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>

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>

Gateway Developer Guide and Reference

19 July 2013

35

Secure Token
Posting To the Hosted Checkout Page

36

19 July 2013

Gateway Developer Guide and Reference

Configuring 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.
NOT E :

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

Gateway Developer Guide and Reference

19 July 2013

37

Configuring Hosted Checkout Pages

Configuring Hosted Pages Using PayPal Manager

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

NOT E :

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

38

19 July 2013

Gateway Developer Guide and Reference

Configuring Hosted Checkout Pages

Configuring Hosted Pages Using PayPal Manager

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

Gateway Developer Guide and Reference

19 July 2013

39

Configuring Hosted Checkout Pages

Configuring Hosted Pages Using PayPal Manager

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

NOT E :

NOT E :

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.
NOT E :

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)
19 July 2013 Gateway Developer Guide and Reference

40

Configuring Hosted Checkout Pages

Using a Secure Token to Pass Hosted Pages Customization Parameters

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

Integrate
This section contains links to PayPal developer resources. PayPals developer portal includes:

Developer integration guides which are comprehensive product guides like this guide.

See the Payflow Gateway product page for links to other useful resources such as SDKs, 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. The table below describes the form post parameters that you can use to dynamically configure the hosted checkout pages.

Gateway Developer Guide and Reference

19 July 2013

41

Configuring Hosted Checkout Pages

Using a Secure Token to Pass Hosted Pages Customization Parameters

Setup Parameters Variable CANCELURL Description 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. Determines if the card security code is required. Values: TRUE or FALSE Determines if the card security code is editable. Values: TRUE or FALSE 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 Send the buyer an email confirmation or not. Default value is FALSE. The URL that customers are directed to if an error occurs. Maximum length: 512 characters. The URL that customers are directed to after a transaction completes successfully. Maximum length: 512 characters. The URL to which the Gateway will send Silent Post. Maximum length: 512 characters. 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 mobileoptimized 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. 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

CSCREQUIRED CSCEDIT DISABLERECEIPT

EMAILCUSTOMER ERRORURL RETURNURL

SILENTPOSTURL TEMPLATE

URLMETHOD

42

19 July 2013

Gateway Developer Guide and Reference

Configuring Hosted Checkout Pages

Using a Secure Token to Pass Hosted Pages Customization Parameters

Customize Parameters Variable PAGECOLLAPSEBGCOLOR Description Sets the color of the border around the embedded template C. Example: PAGECOLLAPSEBGCOLOR=993300 Sets the color of the words Pay with PayPal and Pay with credit or debit card. Example: PAGECOLLAPSETEXTCOLOR=990000 Sets the color of the Pay Now / Submit button. Example: PAGEBUTTONBGCOLOR=AA66FF Sets the color of the text on the Pay Now / Submit button. Example: PAGEBUTTONTEXTCOLOR=33FFFF Sets the color of the text for card number, expiration date, ..etc. Example: LABELTEXTCOLOR=330000

PAGECOLLAPSETEXTCOLOR

PAGEBUTTONBGCOLOR PAGEBUTTONTEXTCOLOR LABELTEXTCOLOR

Other HTML Post Parameters Variable MODE Description (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.
N O TE :

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. Used with the secure token. 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

SECURETOKEN/SECURETOKENID SHOWAMOUNT

Gateway Developer Guide and Reference

19 July 2013

43

Configuring Hosted Checkout Pages

Using the PARMLIST Parameter

Variable SUBTOTAL

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

VERBOSITY

VERIFY

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>

44

19 July 2013

Gateway Developer Guide and Reference

Configuring Hosted Checkout Pages

Hosted Pages and Mobile Browsers

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.
NOT E :

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

Gateway Developer Guide and Reference

19 July 2013

45

Configuring Hosted Checkout Pages

Hosted Pages and Mobile Browsers

supported mobile browser and then explicitly pass the form post parameter: TEMPLATE=MOBILE.

The TEMPLATE form post parameter Layout Layout A Layout B Layout C TEMPLATE parameter value TEMPLATE=TEMPLATEA TEMPLATE=TEMPLATEB TEMPLATE=MINLAYOUT (default) TEMPLATE=MOBILE Behavior on a Mobile Device Auto-redirects to mobile optimized page Auto-redirects to mobile optimized page 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.

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

46

19 July 2013

Gateway Developer Guide and Reference

Configuring Hosted Checkout Pages

Silent Posts

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

NOT E :

Force Silent Post Confirmation

The Force Silent Post Confirmation feature ensures that no transactions proceed unless your Web site receives the Silent Post data. If you enable this feature, Payflow Gateway sends the Silent Post data and waits for a 200 OK from your server (indicating the server's receipt of the data). If Payflow Gateway does not receive the success response, then the transaction is voided and the customer sees a communication error message. In this case, PayPal Manager displays both a transaction that succeeded and a transaction that was voided. To select this feature, be

Gateway Developer Guide and Reference

19 July 2013

47

Configuring Hosted Checkout Pages

Passing Other Data to Your Server Using Post or Silent Post

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.
NOT E :

USER1 through USER10 are not displayed to the customer and are not stored in the PayPal transaction database.

48

19 July 2013

Gateway Developer Guide and Reference

Payflow 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 Each SDK includes full API documentation. 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 210 for more information.

NOT E :

IM PORT AN T :

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 Downloads page, 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.

Gateway Developer Guide and Reference

19 July 2013

49

Payflow SDK
Activating Your Payflow Gateway Account

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

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 https://sandbox.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://pilotpayflowpro.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
NOT E :

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.

50

19 July 2013

Gateway Developer Guide and Reference

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

Gateway Developer Guide and Reference

19 July 2013

51

Sending a Simple Transaction to the Server

Payflow Connection Parameters

COMPANYNAME[14]=Ruff & Johnson COMMENT1[7]=Level=5

NOT E :

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.

52

19 July 2013

Gateway Developer Guide and Reference

Sending a Simple Transaction to the Server

User Parameter Data

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.

Parameter HOSTADDRESS HOSTPORT TIMEOUT

Description (Required) Gateway server name. (Required) Use port 443. (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. (Optional) Proxy server address. Use the PROXY parameters for servers behind a firewall. Your network administrator can provide the values. (Optional) Proxy server port. (Optional) Proxy server logon ID. (Optional) Proxy server logon password.

PROXYADDRESS PROXYPORT PROXYLOGON PROXYPASSWORD

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 USER Description (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 (Required) Your merchant login ID that you created when you registered for the account. Limitations: 64 alphanumeric, case-sensitive characters (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 (Required) The password that you defined while registering for the account. Limitations: 6 to 32 alphanumeric, case-sensitive characters

VENDOR

PARTNER

PWD

Gateway Developer Guide and Reference

19 July 2013

53

Sending a Simple Transaction to the Server

Sale Transaction Example

Sale Transaction Example

In addition to the required connection and user parameters, each transaction type may require other parameters and can include a number of optional parameters. To perform a sale transaction involving a credit card, for example, pass the following parameters:

TRXTYPE - The type of the transaction, such as S for Sale TENDER - The method of payment, such as C for credit card ACCT - The buyer's credit card number AMT - The amount of the sale with two decimal places EXPDATE - The expiration date of the credit card

Typical Sale Transaction

The following is a typical name-value pair string for a sale transaction.
TRXTYPE=S&TENDER=C&USER=MerchantUserID&PWD=Pwd4Gateway&PARTNER=PayPal&ACCT= 5105105105105100&EXPDATE=1215&AMT=23.45&COMMENT1=Airport Shuttle&BILLTOFIRS TNAME=Jamie&BILLTOLASTNAME=Miller&BILLTOSTREET=123 Main St.&BILLTOCITY=San Jose&BILLTOSTATE=CA&BILLTOZIP=951311234&BILLTOCOUNTRY=US&CVV2=123&CUSTIP=0. 0.0.0&VERBOSITY=HIGH

Besides the required sale transaction parameters, the string includes other Payflow parameters typically included in a sale transaction. When the transaction completes, the Gateway server returns a response string made up of NVP response parameters. If the transaction is successful, the Gateway server returns RESULT value 0. The value of PNREF identifies the transaction in future requests, and RESPMSG is a string indicating whether the transaction was approved. The following is an example response:
RESULT=0&PNREF=VXYZ01234567&RESPMSG=APPROVED&AVSADDR=Y&AVSZIP=N&IAVS=Y&CVV2 MATCH=Y

Formatting Payflow Gateway Transactions

For details on how to format a Payflow transaction, see the examples and the supporting documentation provided with your SDK or see Submitting Credit Card Transactions.

54

19 July 2013

Gateway Developer Guide and Reference

6
NOT E :

Submitting 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. 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 (Refund) Transactions on page 67 Submitting Inquiry Transactions on page 69 Submitting Partial Authorizations on page 71 Submitting Purchasing Card Transactions on page 73 Submitting Reference Transactions (Tokenization) on page 73 Submitting Sale Transactions on page 77 Submitting Soft Merchant Information on page 78 Submitting Voice Authorization Transactions on page 79 Submitting Void Transactions on page 80 Using Address Verification Service on page 82 Using Card Security Code on page 82 Information for the PayPal Acquirer on page 83

Gateway Developer Guide and Reference

19 July 2013

55

Submitting Credit Card Transactions

Obtaining an Internet Merchant Account

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.
NOT E :

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.
NOT E :

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.

56

19 July 2013

Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Credit Card Features

Credit Card Features

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

Transaction Type Authorization Account Verification Balance Inquiry Credit Delayed Capture Inquiry Sale Voice Authorization Void

Billable Yes No No Yes No No Yes Yes Yes

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

Gateway Developer Guide and Reference

19 July 2013

57

Submitting Credit Card Transactions

Planning Your Gateway Integration

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.
NOT E :

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).
58
19 July 2013 Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Core Credit Card Parameters

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.
NOT E :

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 TENDER

Description (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. (Required) Indicates the type of transaction to perform. Values are: A = Authorization B = Balance Inquiry C = Credit (Refund) D = Delayed Capture F = Voice Authorization I = Inquiry L = Data Upload N = Duplicate Transaction
N O TE :

TRXTYPE

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

Gateway Developer Guide and Reference

19 July 2013

59

Submitting Credit Card Transactions

Core Credit Card Parameters

Parameter EXPDATE

Description (Required) Expiration date of the credit card. For example, 1215 represents December 2015. Limitations: mmyy format (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 (Optional) Merchant-defined value for reporting and auditing purposes. Limitations: 128 alphanumeric characters (Optional) Merchant-defined value for reporting and auditing purposes. Limitations: 128 alphanumeric characters (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 (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.
N O TE :

AMT

COMMENT1

COMMENT2

CVV2

RECURRING

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

60

19 July 2013

Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Core Credit Card Parameters

Parameter SWIPE

Description (Required for card-present transactions only) Used to pass the Track 1 or Track 2 data (cards magnetic stripe information) for card-present transactions. Include either Track 1 or Track 2 datanot 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.
N O TE :

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.
N O TE :

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 (Optional but recommended) Account holder's last name. Limitations: 30 alphanumeric characters (Optional) The cardholders street address (number and street name). The address verification service verifies the STREET address. Limitations: 150 alphanumeric characters (Optional) Bill-to city. Limitations: 45-character string. (Optional) Bill-to state. Limitations: 2-character string (Varies depending on processor: 2 to 45 characters). Limitations: 10-character string. (Optional) Account holders 5- to 9-digit zip (postal) code. Limitations: 9 characters maximum. Do not use spaces, dashes, or non-numeric characters (Optional) Bill-to country. Limitations: 3-character country code. (Optional) Ship-to first name. Limitations: 30-character string. (Optional) Ship-to last name. Limitations: 30-character string.

BILLTOLASTNAME

BILLTOSTREET

BILLTOCITY

BILLTOSTATE

BILLTOZIP

BILLTOCOUNTRY

SHIPTOFIRSTNAME

SHIPTOLASTNAME

Gateway Developer Guide and Reference

19 July 2013

61

Submitting Credit Card Transactions

Submitting Account Verifications

Parameter SHIPTOSTREET

Description (Optional) Ship-to street address. Limitations: 150-character string. (Optional) Ship-to city. Limitations: 45-character string. (Optional) Ship-to state. Limitations: 2-character string (Varies depending on processor: 2 to 45 characters). Limitations: 10-character string. (Optional) Ship-to postal code. Limitations: 10-character string. (Optional) Ship-to country. Limitations: 3-character country code.

SHIPTOCITY

SHIPTOSTATE

SHIPTOZIP

SHIPTOCOUNTRY

Submitting Account Verifications

Account verification, also known as zero dollar authorization (TRXTYPE=A), verifies credit card information. While you pass TRXTYPE=A for account verification and normal authorization, account verification differs from authorization in the following ways:

Always pass the AMT value 0. If you pass any other amount, the transaction becomes a normal authorization that places a hold on the cardholder's open-to-buy limit. Although the RESULT value returned is 0 (Approved), the RESPMSG value returned is Verified rather than Approved. Payflow returns RESULT value 4, Invalid Amount, if the processor does not support account verifications.

NOT E :

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

Required Account Verification Parameters

To perform account verification, pass the following parameters:

62

19 July 2013

Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Submitting Authorization/Delayed Capture Transactions

Parameter TRXTYPE

Description (Required) Set to A. Limitations: 1 alphanumeric character. (Required) Set to 0. (Required) Set to HIGH to obtain information about a partial authorization in the response.

AMT VERBOSITY

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-0111 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.
NOT E :

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.

Gateway Developer Guide and Reference

19 July 2013

63

Submitting Credit Card Transactions

Submitting Balance Inquiry Transactions
NOT E :

If you signed up for the PayPal processor with Fraud Protection Services, use delayed capture processing for all sale transactions.

If your business provides immediate fulfillment and you are not using the PayPal processor with Fraud Protection Services, you can use a simple sale transaction instead. For details, see Submitting Sale Transactions on page 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 73.
NOT E :

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:

Parameter ORIGID

Description (Required by some transaction types) ID of the original transaction referenced. The PNREF parameter returns this ID, and it appears as the Transaction ID in PayPal Manager reports. Limitations: 12 case-sensitive alphanumeric characters.

Submitting 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.
NOT E :

Payflow returns RESULT value 3, Invalid Transaction Type, if the processor does not support balance inquiry.

Processing Platforms Supporting Balance Inquiry Transactions

The following processing platforms currently support pre-paid card balance inquiry transactions. This feature will be added for more processors in the near future. As more processors are added, this list will be updated accordingly.
WorldPay

64

19 July 2013

Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Submitting Card Present (SWIPE) Transactions

Required Balance Inquiry Parameters

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

Parameter TRXTYPE

Description (Required) Set to B. Limitations: 1 alphanumeric character. (Required) Expiration date of the pre-paid card in the format MMYY. For example, 1215 represents December 2015. (Required) Set to HIGH to obtain information about a balance inquriy in the response.

EXPDATE VERBOSITY

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-0216 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).
NOT E :

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

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

Contact your merchant account provider to make sure that they support card-present transactions. Contact PayPal Customer Service to request them to set up your account properly for accepting and passing swipe data. If you plan to process card-present as well as card-not-present transactions, set up 2 separate Gateway accounts. Request that one account be set up for card-present transactions, and use it solely for that purpose. Use the other for card-not-present transactions. Using the wrong account may result in downgrades. A sale is the preferred method to use for card-present transactions. Consult with your acquiring bank for recommendations on other methods.

Gateway Developer Guide and Reference

19 July 2013

65

Submitting Credit Card Transactions

Submitting Card Present (SWIPE) Transactions

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 Vantiv WorldPay

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

66

19 July 2013

Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Submitting Credit (Refund) Transactions
NOT E :

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 (Refund) 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 (nonreferenced) depending on how your account is setup. To issue a credit, the original transaction can only be one of the following: a Sale (TRXTYPE=S), Delayed Capture (TRXTYPE=D) or Voice Authorization (TRXTYPE=F). It is recommended that the merchant issue a credit only if the original transaction has already settled. Even though it is possible to issue a credit to a transaction that has not settled, it is recommended that you void such transactions. Both the credit transaction and the original transaction will appear on the customer's statement.

Required Credit Transaction Parameters

The required parameter data for a credit transaction depends on the Allow Non-referenced Credits security setting for your Payflow account. A non-referenced credit is a credit transaction that does not use the credit card information from an existing transaction. You provide the credit card information. As an example, Sally Smith calls you on the phone to cancel an order from your business. To refund her money, you credit her credit card by submitting a non-referenced credit transaction. Guidelines and parameter requirements for credit transactions differ depending on whether non-referenced credits are allowed.
Non-Referenced Credits Not Allowed

When non-referenced credits are not allowed (the setting recommended by PayPal), credit transactions are permitted only against existing sale, delayed capture, and voice authorization transactions. To submit a credit transaction when non-referenced credits are not allowed, pass the following parameter:

Parameter ORIGID

Description (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

19 July 2013

67

Submitting Credit Card Transactions

Submitting Credit (Refund) Transactions

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 The default security setting for Gateway accounts is Allow non-referenced credits = No. Sending the ORIGID is the preferred method for performing credit transactions, as described in Non-Referenced Credits Not Allowed. Using the ACCT, EXPDATE, or AMT parameters for such restricted accounts leads to the return of RESULT value 117 (failed the security check). To help reduce fraud, PayPal recommends that you do not activate non-referenced credits unless you have a business reason. For information on configuring your security settings, see PayPal Manager online help.

NOT E :

Example

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 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.)
NOT E :

These fields are not copied for referenced credits: TAXAMT, TAXEXEMPT, DUTYAMT, FREIGHTAMT, and (for American Express only) DESC4. 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.

NOT E :

ACCT BILLTOEMAIL BILLTOSTATE

AMT BILLTOMIDDLENAME BILLTOSTREET

BILLTOCITY BILLTOLASTNAME BILLTOZIP

BILLTOCOUNTRY BILLTOPHONENUM COMMENT1

68

19 July 2013

Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Submitting Inquiry Transactions

COMMENT2 EXPDATE SHIPTOCOUNTRY SHIPTOSTATE

COMPANYNAME INVNUM SHIPTOFIRSTNAME SHIPTOSTREET

CUSTCODE PONUM SHIPTOMIDDLENAME SHIPTOZIP

CUSTIP SHIPTOCITY SHIPTOLASTNAME SWIPE

Submitting Inquiry Transactions

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

When To Use an Inquiry Transaction

You perform an inquiry using a reference to an original transactioneither 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:

Parameter ORIGID

Description (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.

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

Gateway Developer Guide and Reference

19 July 2013

69

Submitting Credit Card Transactions

Submitting Inquiry Transactions

Required Parameters When Using the CUSTREF

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

Parameter CUSTREF

Description (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 (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 (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
NOT E :

STARTTIME

ENDTIME

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:

70

19 July 2013

Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Submitting Partial Authorizations

Parameter SECURETOKEN

Description (Required) A value the Payflow server created upon your request for storing transaction data. Limitations: 32 alphanumeric characters

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

Inquiry Parameter String Using the Secure Token

The following is an example inquiry request string with the SECURETOKEN parameter.
TRXTYPE=I&TENDER=C&PARTNER=PayPal&PWD=SuperUserPassword&USER=SuperMerchant& VERBOSITY=HIGH&VENDOR=SuperMerchant&SECURETOKEN=FmyM1y7wy8kiS6aumnMPhTQN&VE RBOSITY=HIGH

The following is the response string.

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

Gateway Developer Guide and Reference

19 July 2013

71

Submitting Credit Card Transactions

Submitting Partial Authorizations

Accept the $80.00 and ask the buyer to provide an alternate payment for the additional $20.00. Reject the partial authorization and submit to the card issuer an authorization reversal (Void) for $80.00.

Required Partial Authorization Parameters

To perform a partial authorization, pass the same parameters that you would for an authorization (TRXTYPE=A, ACCT, AMT, and EXPDATE). In addition, pass the following parameters.

Parameter PARTIALAUTH

Description (Required) Set to Y to submit a partial authorization. Limitations: 1 alphanumeric character. (Required) Set to HIGH to obtain information about a partial authorization in the response.

VERBOSITY

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.

72

19 July 2013

Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Submitting Purchasing Card Transactions

Reject the partial authorization by sending the card issuer an authorization reversal (void) for $80.

Submitting Purchasing Card Transactions

A purchasing card (also referred to as a commercial card, corporate card, procurement card or business card) is a credit card that an employer requests to be issued. A purchasing card is usually reserved for business-related charges. The card issuer provides specialized reporting for this card type so the employer can monitor the use of the card. There is no method for determining whether a card is a purchase card or a commercial card based on the card number. To obtain the best bank interchange rates for commercial cards, pass specific additional transaction information. Purchasing card support and parameters vary from processor to processor. See Submitting Purchasing Card Level 2 and 3 Transactions on page 153.
NOT E :

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. For transactions processed by the PayPal processor, use the PPREF returned in the original transaction as the transaction ID, instead of the PNREF.

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 Joes 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 Joes credit card without having to ask him again for credit card information.
NOT E :

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.

Gateway Developer Guide and Reference

19 July 2013

73

Submitting Credit Card Transactions

Submitting Reference Transactions (Tokenization)

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.
NOT E :

When the Gateway looks up the reference transaction, it does not alter in any way the transaction referenced or any other transaction in the database. A reference transaction is a read-only operation. Payflow populates with data and acts upon the new transaction only. It does not maintain any linkage between the reference transaction and the new transaction.

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

Transaction Types That Can Be Used As the Original Transaction

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

Authorization (To capture the funds for an approved authorization transaction, be sure to perform a delayed capture transactionnot a reference transaction.) Credit Delayed capture Sale Voice authorization (Payflow does not copy the voice authorization code to the new transaction) Void

Fields Copied From Reference Transactions

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

ACCT EXPDATE BILLTOFIRSTNAME BILLTOMIDDLENAME BILLTOLASTNAME BILLTOSTREET

BILLTOCITY BILLTOSTATE BILLTOZIP BILLTOCOUNTRY SWIPE

74

19 July 2013

Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Submitting Reference Transactions (Tokenization)

Example Reference Transaction

In this example, you authorize an amount of $100 for a shipment and charge $66 for the first partial shipment using a normal delayed capture. You charge the $34 for the final part of the shipment using a reference transaction to draw credit card and shipping address information from the initial authorization transaction. This example procedure creates a reference transaction: 1. Submit the initial transaction, such as an authorization. You use an authorization transaction for the full amount of the purchase of $100 as shown in this transaction request:
TRXTYPE=A&TENDER=C&PWD=x1y2z3&PARTNER=PayPal&VENDOR=SuperMerchant&USER=Supe rMerchant&ACCT=5555555555554444&EXPDATE=1215&AMT=100.00&INVNUM=123456789&BI LLTOSTREET=5199 MAPLE&BILLTOZIP=94588

Note the value of the PNREF in the response:

RESULT=0&PNREF=VXYZ01234567&RESPMSG=APPROVED&AUTHCODE=123456&AVSADDR=Y&AVSZ IP=N
NOT E :

The PNREF returned in the original transaction is valid in reference transactions for 12 months. For transactions processed by the PayPal processor, Payflow uses the value of the PPREF response parameter as the transaction ID, instead of the PNREF parameter.

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

For transactions processed by the PayPal processor, capture the value of the PPREF returned in the original transaction, and pass it in the ORIGPPREF parameter. Also, if the original transaction was created using ExpressCheckout or a Billing Agreement, set the TENDER parameter to TENDER=P.

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

Gateway Developer Guide and Reference

19 July 2013

75

Submitting Credit Card Transactions

Submitting Reference Transactions (Tokenization)

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

For transactions processed by the PayPal processor, capture the value of the PPREF returned in the original transaction, and pass it in the ORIGPPREF parameter. Also, if the original transaction was created using ExpressCheckout or a Billing Agreement, set the TENDER parameter to TENDER=P.

Data Upload - Storing Credit Card Data on the Gateway Server

To facilitate creating reference transactions while assisting you with PCI compliance, PayPal allows you to upload credit card data by submitting an upload transaction (TRXTYPE=L). At minimum, you must pass values for the following parameters:

TRXTYPE TENDER ACCT EXPDATE

This is an example upload transaction request:

TRXTYPE=L&TENDER=C&ACCT=5105105105105100&EXPDATE=1215&BILLTOFIRSTNAME=Ted&B ILLTOLASTNAME=Smith&BILLTOSTREET=123&BILLTOCITY=SanJose&BILLTOSTATE=CA&BILL TOZIP=12345&BILLTOPHONENUM=123-123-1234

This is the response:

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

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.
NOT E :

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.

76

19 July 2013

Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Submitting Sale Transactions

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.
NOT E :

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

NOT E :

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 customer's street address (BILLTOSTREET) and zip code (BILLTOZIP) to use address verification service. To validate card security codes, pass the CVV2 parameter. For details on address verification service and card security code, see the following:

Gateway Developer Guide and Reference

19 July 2013

77

Submitting Credit Card Transactions

Submitting Soft Merchant Information

Submitting Card Present (SWIPE) Transactions on page 65 Using Card Security Code on page 82

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.

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

78

19 July 2013

Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Submitting Voice Authorization Transactions

MERCHANTCOUNTRYCODE MERCHANTLOCATIONID MERCHANTID MERCHANTCONTACTINFO 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.

NOT E :

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 merchants telephone number, e-mail address, or website URL

To use merchant descriptors, you are not required to have the processor set the division level flag. However, you are required to obtain prior risk or credit department approval before sending the parameters.

Submitting Voice Authorization Transactions

A voice authorization (TRXTYPE=F) is a transaction that the processing network authorizes over the phone.
NOT E :

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.

Gateway Developer Guide and Reference

19 July 2013

79

Submitting Credit Card Transactions

Submitting Void Transactions

Required Voice Authorization Transaction Parameters

To perform a voice authorization transaction, pass the AUTHCODE provided by your merchant bank.
Parameter AUTHCODE Description (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

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

TRXTYPE=F&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant&P WD=x1y2z3&AUTHCODE=AB3456&ACCT=5555555555554444&EXPDATE=1215&AMT=123.00&VER BOSITY=HIGH

Submitting Void Transactions

The void transaction (TRXTYPE=V) prevents authorizations from being captured, and delayed captures, sales and voice authorizations from being settled. You cannot void another void transaction or any inquiry type transactions. The void transaction and the original transaction will not appear on the customer's statement. PayPal will issue an authorization reversal as part of the void transaction for debit and credit cards if the processor supports it. Because the bank or issuer ultimately decides whether to honor authorization reversals, there is no accurate way to determine if an authorization reversal was completed and the hold on funds has been removed.

When To Use a Void Transaction

Use the following guidelines when using void transactions:

You can void delayed capture, sale, credit, authorization, and voice authorization transactions. You cannot void a void transaction. You can only use a void transaction on a transaction that has not yet settled. To refund a customer's money for a settled transaction, submit a credit transaction.

Required Void Transaction Parameters

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

80

19 July 2013

Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Submitting Void Transactions

Parameter ORIGID

Description (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

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.)
NOT E :

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.

ACCT COMMENT2 CUSTIP BILLTOFIRSTNAME INVNUM SHIPTOFIRSTNAME SHIPTOSTREET SWIPE BILLTOZIP

AMT COMPANYNAME DUTYAMT BILLTOMIDDLENAME PONUM SHIPTOMIDDLENAME SHIPTOZIP TAXAMT

BILLTOCITY BILLTOCOUNTRY BILLTOEMAIL BILLTOLASTNAME SHIPTOCITY SHIPTOLASTNAME BILLTOSTATE BILLTOPHONENUM

COMMENT1 CUSTCODE EXPDATE FREIGHTAMT SHIPTOCOUNTRY SHIPTOSTATE BILLTOSTREET TAXEXEMPT

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

Gateway Developer Guide and Reference

19 July 2013

81

Submitting Credit Card Transactions

Using Address Verification Service

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 = no match, 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.
NOT E :

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).
NOT E :

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

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 buyer's possession.

82

19 July 2013

Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Information for the PayPal Acquirer

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.
NOT E :

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

Payflow returns the raw response from the processor in the PROCCVV2 parameter. For details on the meaning of the response, contact your merchant bank.

Information for the PayPal Acquirer

If PayPal is your acquirer, use the following PayPal specific codes.

Countries and Regions Supported by PayPal

PayPal uses 2-character IS0-3166-1 codes for specifying countries and regions that are supported in fields and variables.

Gateway Developer Guide and Reference

19 July 2013

83

Submitting Credit Card Transactions

Information for the PayPal Acquirer

For a complete list of countries and regions supported by PayPal and their 2-character ISO3166-1 codes, please refer to the PayPal API reference list of Countries and Regions.

PayPal Currency Codes

PayPal uses 3-character ISO-4217 codes for specifying currencies in fields and variables. Please refer to the table of currencies supported by PayPal.

84

19 July 2013

Gateway Developer Guide and Reference

Testing 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 American Express American Express Corporate

378282246310005 371449635398431 378734493671000

Gateway Developer Guide and Reference

19 July 2013

85

Testing Transactions
Processors Other Than PayPal

Diners Club Discover Discover JCB JCB MasterCard MasterCard Visa Visa Visa

38520000023237 6011111111111117 6011000990139424 3530111333300000 3566002020360505 5555555555554444 5105105105105100 4111111111111111 4012888888881881 4222222222222
NOT E :

Even though this number has a different character count than the other test numbers, it is the correct and functional number.

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.

Amount $0 $1000 $1001 $2000

Result RESULT value 0 (Approved) 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). RESULT value 12 (Declined) Result Values Based On Amount Submitted and Processor

$2001+

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

Processing Platform American Express Brighton Elavon

RESULT Values Available for Testing 0, 12, 13, 104, 1000 0, 12, 13, 104

86

19 July 2013

Gateway Developer Guide and Reference

Testing Transactions
Processors Other Than PayPal

Processing Platform First Data Merchant Services North First Data Merchant Services Nashville First Data Merchant Services South Global Payments Central Global Payments East Paymentech Salem (New Hampshire) Paymentech Tampa TSYS Acquiring Solutions Vantiv (formerly Fifth Third Processing Solutions)

RESULT Values Available for Testing 0, 4, 5, 12, 13, 23, 24,114, 1000 0, 12, 13, 104 0, 12, 13, 104 0, 4, 5, 8, 12, 13, 23, 24, 104, 111, 114, 1000 0, 4, 5, 12, 13, 23, 24, 30, 100, 104, 114, 1000 0, 12, 13, 104 0, 3, 4, 5, 12, 13, 23, 24, 1000 0, 4, 12, 13, 23, 104, 114, 1000 0, 4, 5, 12, 13, 23, 24,114, 1000

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.

RESULT value 0

Definition Approved

How to test using Payflow Gateway 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 Use an invalid PWD Use an invalid TENDER, such as G Use an invalid TRXTYPE, such as G Use an invalid AMOUNT, such as 1 Use the AMOUNT 1005 - Applies only to the following processors: Global Payments East and Central, and American Express Submit a delayed capture transaction with no ORIGID Use the AMOUNT 1012 or an AMOUNT of 2001 or more Use the AMOUNT 1013

1 2 3 4 5

User authentication failed Invalid tender Invalid transaction type Invalid amount Invalid merchant information

7 12 13

Field format error Declined Referral

Gateway Developer Guide and Reference

19 July 2013

87

Testing Transactions
Processors Other Than PayPal

RESULT value 19 22 23 24 25

Definition Original transaction ID not found Invalid ABA number Invalid account number Invalid expiration date Transaction type not mapped to this host (Processor) Invalid XML document Duplicate Transaction

How to test using Payflow Gateway Submit a delayed capture transaction with an invalid ORIGID Applies only to ACH transactions submit an invalid ABA number (8 digits) Submit an invalid account number, for example, 000000000000000 Submit an invalid expiration date, for example, 0298 Submit a transaction for a card or tender you are not currently set up to accept, for example, a Diners card if you arent set up to accept Diners Pass a bad XML document (XMLPay users only) Use the AMOUNT 1030 - Only applies to Global Payments East and Global Payments Central processors Use the AMOUNT 1050 - Only applies to Paymentech Use the AMOUNT 1099 - Only applies to Global Payments East Use the AMOUNT 1100 - Only applies to Global Payments East and Central Set timeout value to 1 Use the AMOUNT 1103 Use the AMOUNT 1104 Attempt to credit an authorization Attempt to void a captured authorization Capture an authorization transaction twice or attempt to capture a transaction that is not an authorization transaction 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 Applies to ACH transactions only

29 30

50 99 100 101 103 104 105 108 111

Insufficient funds available General error Invalid transaction returned from host (Processor) Time-out value too small Error reading response from host (Processor) Timeout waiting for processor response Credit error Void error Capture error

112

Failed AVS check

113

Cannot exceed sales cap

88

19 July 2013

Gateway Developer Guide and Reference

Testing Transactions
Processors Other Than PayPal

RESULT value 114

Definition CVV2 Mismatch

How to test using Payflow Gateway Use the AMOUNT 1114. Only applies to TSYS Acquiring Solutions, Merchant e-Solutions, and Global Payments East and Global Payments Central processors Use the AMOUNT 2000 - Does not apply to Elavon (formerly Nova), American Express, or Global Payments East processors

1000

Generic Host (Processor) Error

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.

Submitted Value for BILLTOSTREET 000-333 334-666 667 or higher or begins with a nonnumeric character

Example BILLTOSTREET Value 24285 Elm 49354 Main 79232 Maple

AVSADDR Result Y N X

The following table tests AVSZIP.

Submitted Value for BILLTOZIP 00000-50000 50001-99999 Any value (if street address is 667 or higher or begins with a non-numeric character)

Example BILLTOZIP Value 00382 94303 BILLTOSTREET=79232 Maple, BILLTOZIP=20304

AVSZIP Result Y N X

Gateway Developer Guide and Reference

19 July 2013

89

Testing Transactions
Processors Other Than PayPal

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.
NOT E :

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 CVV2 Value 000 001-300 301-600 601 or higher CVV2MATCH Value Y Y N X

Testing the Litle Automatic Account Updater Feature

The Litle Automatic Account Updater feature identifies outdated card information, repairs it, and substitutes new card information before submitting the transaction to the network. See the Litle Automatic Account Updater on page 110 section for more information. Merchants utilizing this feature should check for the presence of the CCUPDATED=Y response parameter, and if it is returned, should also check for the presence of the ACCT and EXPDATE response parameters to determine what card information has been updated. Merchants can test their integration for the Litle Automatic Account Updater feature in the Payflow pilot test environment by doing the following. 1. In the ACCT request parameter, pass one of the following testing card numbers:
Updated card number returnedin ACCT response parameter 4321432143214321 4012000033330026 5454545454545454 5105105105105100

Card number passed in ACCT request parameter 4111111111111111 4012888888881881 5105105105105100 5560136761278244
NOT E :

Only the last 4-digits of the updated credit card number will be returned.

90

19 July 2013

Gateway Developer Guide and Reference

Testing Transactions
PayPal Processor

2. In the EXPDATE request parameter, pass one of the following expiration dates:
Expiration date passedin EXPDATE request parameter 0000 1213 0120 0230 0340 Updated expiration date returnedin EXPDATE response parameter 0919 1218 0150 0250 0350

3. In the AMT request parameter, pass an amount that falls within one of the following ranges to bring about different account updater test cases:

Amount passedin AMT request parameter 1000.00 > AMT >= 500.00 500.00 > AMT >= 400.00 400.00 > AMT >= 300.00

Test case Both an updated credit card number and an updated expiration date Only an updated credit card number Only an updated expiration date

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.

American Express American Express Amex Corporate Australian BankCard Diners Club Diners Club Discover

378282246310005 371449635398431 378734493671000 5610591081018250 30569309025904 38520000023237 6011111111111117

Gateway Developer Guide and Reference

19 July 2013

91

Testing Transactions
PayPal Processor

Discover JCB JCB MasterCard MasterCard Visa Visa Visa

6011000990139424 3530111333300000 3566002020360505 5555555555554444 5105105105105100 4111111111111111 4012888888881881 4222222222222

NOT E :

Even though this number has a different character count than the other test numbers, it is the correct and functional number.

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.

Result 0 3 4

Definition Approved Invalid transaction type Invalid amount

How to test Use an AMOUNT of 10000 or less Use the AMOUNT 10402 Use any of these as AMOUNT: 10400 10401 10403 10404 Use any of these as AMOUNT: 10548 10549

Invalid merchant information

92

19 July 2013

Gateway Developer Guide and Reference

Testing Transactions
PayPal Processor

Result 7

Definition Field format error

How to test 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 Use any of these as AMOUNT: 10417 15002 15005 15006 15028 15039 10544 10545 10546 Use the AMOUNT 10422 Use any of these as AMOUNT: 10519 10521 10522 10527 10535 10541 10543

12

Declined

13 23

Referral Invalid account number

Gateway Developer Guide and Reference

19 July 2013

93

Testing Transactions
PayPal Processor

Result 24

Definition Invalid expiration date

How to test Use any of these as AMOUNT: 10502 10508 Use the AMOUNT 10536 Attempt to credit an authorization Use the AMOUNT 10505 Use the AMOUNT 10504 Use an AMOUNT other than those listed in this column

30 105 112 114 1000

Duplicate Transaction Credit error Failed AVS check CVV2 Mismatch Generic Host (Processor) Error

94

19 July 2013

Gateway Developer Guide and Reference

Transaction Responses

When a transaction finishes, the Payflow server returns a response string made up of namevalue 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 PNREF

Description Gateway transaction ID, a unique number that identifies the transaction. Character length and limitations: 12 alphanumeric characters PayPal transaction ID of the payment; returned by the PayPal processor. Character length and limitations: 17-character string The outcome of the attempted transaction. RESULT=0 means the transaction was approved.
NOTE:

PPREF

RESULT

For account verification transactions, RESULT=0 with RESPMSG=Verified means a zero dollar authorization has been successfully performed. 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:

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)

Gateway Developer Guide and Reference

19 July 2013

95

Transaction Responses
Credit Card Transaction Responses

Field RESPMSG

Description 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. 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. For partial authorizations, RESPMSG=Partial Approval when RESULT=0.

NOTE:

NOTE:

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

AVSADDR

AVSZIP

IAVS

PROCAVS

PROCCVV2

96

19 July 2013

Gateway Developer Guide and Reference

Transaction Responses
Credit Card Transaction Responses

Field HOSTCODE

Description 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 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 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 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 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. (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 (PayPal only.) Value used for tracking this Direct Payment transaction. Character length and limitations: 13 alphanumeric characters Unique transaction ID returned when VERBOSITY=HIGH for tracking American Express CAPN transactions on non-PayPal processors.
NOTE:

RESPTEXT

PROCCARDSECURE

ADDLMSGS

PAYMENTTYPE

CORRELATIONID

AMEXID

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 ORIGAMT This field returns the transaction amount or if performing a partial authorization it will return the amount approved for the partial authorization. Partial authorizations: Original amount submitted for authorization.

Gateway Developer Guide and Reference

19 July 2013

97

Transaction Responses
Credit Card Transaction Responses

Field CARDTYPE

Description 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 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) 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) Additional processor-related messages. 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 Is returned with one of the following values: DUPLICATE=2 ORDERID has already been submitted in a previous request with the same ORDERID. DUPLICATE=1 The request ID has already been submitted for a previous request. DUPLICATE=-1 The Gateway database is not available. PayPal cannot determine whether this is a duplicate order or request. The date a transaction will settle. This parameter is returned in the response for inquiry transactions only (TRXTYPE=I). A processor response code typically returned on declined recurring transactions. Its purpose is to provide merchants with information and specific instructions on how to handle the decline. It is the merchants responsibility to follow the instructions provided in order to avoid chargebacks. For details on the meanings of these codes, see: https://merchant.paypal.com/us/cgi-bin/?&cmd=_rendercontent&content_ID=merchant/cc_compliance_error_codes
NOTE:

EMAILMATCH

PHONEMATCH

EXTRSPMSG TRANSTIME

DUPLICATE

DATE_TO_SETTLE PAYMENTADVICECODE

If a recurring transaction is declined with a returned PAYMENTADVICECODE value of 03 or 21, it is the merchant's responsibility to stop this recurring transaction. These two codes indicate that either the account was closed, fraud was involved, or the cardholder has asked the bank to stop this payment for another reason. Even if a reattempted transaction is successful, it will likely result in a chargeback.

98

19 July 2013

Gateway Developer Guide and Reference

Transaction Responses
Address Verification Service Responses From PayPal

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.

PayPal processor AVS code A B C D E F G I N P R S U W X Y Z All other

Meaning Address International A International N International X Not allowed for MOTO (Internet/Phone) transactions UK-specific X Global Unavailable International Unavailable No Postal (International Z) Retry Service not Supported Unavailable Whole Zip Exact Match Yes Zip

AVSADDR Y Y N Y X Y X X N N X X X N Y Y N X

AVSZIP N N N Y X Y X X N Y X X X Y Y Y Y X

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

Gateway Developer Guide and Reference

19 July 2013

99

Transaction Responses
Card Security Code Results

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

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 Processor CVV2 Code M N P S U X All other

PayPal Processor Code Description Match No Match Not Processed Service Not Supported Unavailable No Response

PROCVV2MATCH Y N X X X X X

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.
NOT E :

Not all processors support BALAMT when a transaction involves a stored value card.
19 July 2013 Gateway Developer Guide and Reference

100

Transaction Responses
PNREF

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 ACRAF23DB3C4 Printable characters also include symbols other than letters and numbers such as the question mark (?). A PNREF value typically contains letters and numbers only.

NOT E :

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.
NOT E :

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.

Gateway Developer Guide and Reference

19 July 2013

101

Transaction Responses
RESULT Values and RESPMSG Text

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

RESPMSG and Explanation Approved

N O TE :

PayPal processor: Warning information may be returned that may be useful to the request applicaton. See the PayPal API error codes documentationon the PayPal developer website for information on corrective actions.

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 Invalid tender type. Your merchant bank account does not support the following credit card type that was submitted. Invalid transaction type. Transaction type is not appropriate for this transaction. For example, you cannot credit an authorization-only transaction Invalid amount format. Use the format: #####.## Do not include currency symbols or commas. Invalid merchant information. Processor does not recognize your merchant account information. Contact your bank account acquirer to resolve this problem. Invalid or unsupported currency code Field format error. Invalid information entered. See RESPMSG.

2 3 4 5 6 7

102

19 July 2013

Gateway Developer Guide and Reference

Transaction Responses
RESULT Values and RESPMSG Text

RESULT 8 9 10 11 12

RESPMSG and Explanation Not a transaction server Too many parameters or invalid stream Too many line items Client time-out waiting for response 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. 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. Original transaction ID not found. The transaction ID you entered for this transaction is not valid. See RESPMSG. Cannot find the customer reference number Invalid ABA number Invalid account number. Check credit card number and bank account number and resubmit. Invalid expiration date. Check card expiration date and re-submit. 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. 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. Insufficient partner permissions Insufficient user permissions Invalid XML document. This could be caused by an unrecognized XML tag or a bad XML format that cannot be parsed by the system. Duplicate transaction Error in adding the recurring profile Error in modifying the recurring profile Error in canceling the recurring profile Error in forcing the recurring profile

13

19 20 22 23 24 25

26

27 28 29 30 31 32 33 34

Gateway Developer Guide and Reference

19 July 2013

103

Transaction Responses
RESULT Values and RESPMSG Text

RESULT 35 36 37 50 51 52 99 100 101

RESPMSG and Explanation Error in reactivating the recurring profile OLTP Transaction failed Invalid recurring profile ID Insufficient funds available in account Exceeds per transaction limit Permission issue. Attempting to perform a transaction type, such as Sale or Authorization, that is not allowed for this account. General error. See RESPMSG. Transaction type not supported by host Time-out value too small PayPal Australia: Invalid transaction returned from host (can be treated as an invalid transaction or a decline) 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. 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. 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. 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.)

102

103

104

105

104

19 July 2013

Gateway Developer Guide and Reference

Transaction Responses
RESULT Values and RESPMSG Text

RESULT 106

RESPMSG and Explanation 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. Duplicate suppression time-out 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) 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. Referenced auth (against order) Error 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. Failed AVS check. Address and zip code do not match. An authorization may still exist on the cardholders account. Merchant sale total will exceed the sales cap with current transaction. ACH transactions only. Card Security Code (CSC) Mismatch. An authorization may still exist on the cardholders account. System busy, try again later Failed to lock terminal number. Please try again later. For Moneris Solutions, another transaction or settlement is in process. Rerun the transaction later. 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. Invalid keywords found in string fields Attempt to reference a failed transaction Not enabled for feature Merchant sale total will exceed the credit cap with current transaction. ACH transactions only. Fraud Protection Services Filter Declined by filters

107 108

109

110 111

112 113 114 115 116 117

118 120 121 122 125

Gateway Developer Guide and Reference

19 July 2013

105

Transaction Responses
RESULT Values and RESPMSG Text

RESULT 126

RESPMSG and Explanation Fraud Protection Services Filter Flagged for review by filters
N O TE :

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 128 132 133 150 Fraud Protection Services Filter Not processed by filters Fraud Protection Services Filter Declined by merchant after being flagged for review by filters Card has not been submitted for update Data mismatch in HTTP retry request 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. Issuing bank unavailable 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. 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. Secure Token Expired. The time limit of 20 minutes has expired and the token can no longer be used. Reauth error Order error Cybercash Batch Error Cybercash Query Error Generic host error. This is a generic message returned by your credit card processor. The RESPMSG will contain more information describing the error. Buyer Authentication Service unavailable Buyer Authentication Service Transaction timeout Buyer Authentication Service Invalid client version Buyer Authentication Service Invalid timeout value

151 160

161 162 200 201 600 601 1000 1001 1002 1003 1004

106

19 July 2013

Gateway Developer Guide and Reference

Transaction Responses
RESULT Values and RESPMSG Text

RESULT 1011 1012 1013 1014 1016

RESPMSG and Explanation Buyer Authentication Service unavailable Buyer Authentication Service unavailable Buyer Authentication Service unavailable Buyer Authentication Service Merchant is not enrolled for Buyer Authentication Service (3-D Secure) 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. 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. Buyer Authentication Service Invalid card type Buyer Authentication Service Invalid or missing currency code Buyer Authentication Service merchant status for 3D secure is invalid Buyer Authentication Service Validate Authentication failed: missing or invalid PARES Buyer Authentication Service Validate Authentication failed: PARES format is invalid Buyer Authentication Service Validate Authentication failed: Cannot find successful Verify Enrollment Buyer Authentication Service Validate Authentication failed: Signature validation failed for PARES Buyer Authentication Service Validate Authentication failed: Mismatched or invalid amount in PARES Buyer Authentication Service Validate Authentication failed: Mismatched or invalid acquirer in PARES Buyer Authentication Service Validate Authentication failed: Mismatched or invalid Merchant ID in PARES Buyer Authentication Service Validate Authentication failed: Mismatched or invalid card number in PARES Buyer Authentication Service Validate Authentication failed: Mismatched or invalid currency code in PARES Buyer Authentication Service Validate Authentication failed: Mismatched or invalid XID in PARES Buyer Authentication Service Validate Authentication failed: Mismatched or invalid order date in PARES

1017

1021 1022 1023 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051

Gateway Developer Guide and Reference

19 July 2013

107

Transaction Responses
RESULT Values and RESPMSG Text

RESULT 1052

RESPMSG and Explanation Buyer Authentication Service Validate Authentication failed: This PARES was already validated for a previous Validate Authentication transaction

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.

RESULT -1 -2 -5 -6 -7 -8 -9 -10 -11 -12 -13 -14 -15 -20 -21 -22

Description Failed to connect to host Failed to resolve hostname Failed to initialize SSL context Parameter list format error: & in name Parameter list format error: invalid [ ] name length clause SSL failed to connect to host SSL read failed SSL write failed Proxy authorization failed Timeout waiting for response Select failure Too many connections Failed to set socket options Proxy read failed Proxy write failed Failed to initialize SSL certificate

108

19 July 2013

Gateway Developer Guide and Reference

Transaction Responses
Processor-specific Response Parameters

RESULT -23 -24 -25 -26 -27 -28 -29 -30 -31 -32 -40 -41 -99 -100 -103 -104 -105 -106 -107 -108 -109 -111 -113

Description Host address not specified Invalid transaction type Failed to create a socket Failed to initialize socket layer Parameter list format error: invalid [ ] name length clause Parameter list format error: name Failed to initialize SSL connection Invalid timeout value The certificate chain did not validate, no local certificate found The certificate chain did not validate, common name did not match URL Unexpected Request ID found in request Required Request ID not found in request Out of memory Parameter list cannot be empty Context initialization failed Unexpected transaction state Invalid name value pair request Invalid response format This XMLPay version is not supported The server certificate chain did not validate Unable to do logging The following error occurred while initializing from message file: <Details of the error message> Unable to round and truncate the currency value simultaneously

Processor-specific Response Parameters

Some of the response parameters returned in a Payflow transaction are processor-specific and are returned only to merchants using a certain processing platform. For a list of processing platforms supported by Payflow, see Processing Platforms Supporting Card-Present Transactions on page 28.

Litle Response Parameters on page 110

Gateway Developer Guide and Reference

19 July 2013

109

Transaction Responses
Processor-specific Response Parameters

Litle Response Parameters

Merchants using the Litle processing platform may see the following transaction response parameters.
Parameter TYPE Description Defines the type of account used in the transaction in terms of card association, card company, Bill Me Later, PayPal, or eCheck. Has two possible values: MASS AFFLUENTReturned for certain Visa and MasterCard cards indicating high income customers (>100K annual income). AFFLUENT Returned for certain Visa and MasterCard cards indicating high income customers with high spending patterns (>100K annual income and >40K in card usage). Litle Automatic Account Updater

AFFLUENT

The Litle Automatic Account Updater feature identifies outdated payment card information, repairs it, and substitutes new card information before submitting the transaction to the network. To use this feature, you must sign up directly with Litle. For more information, see: http://www.litle.com/products-services/processing/recovery-services/automatic-account-updater/. After signing-up for this feature, Payflow merchants will receive a few extra transaction response parameters only for transactions in which the customers account information has been updated. If the customers card number and/or expiration date are currently different from the information passed in the Payflow transaction request, merchants will receive some or all of the following transaction response parameters.
Parameter CCUPDATED=Y ACCT Description This response parameter is returned if either or both the account number and expiration date have changed. If the card number has changed, the last 4-digits of the new card number will also be returned in the ACCT response parameter. Should you require the full credit card number you will need to contact Litle to obtain the complete card number. If the card expiration date has changed, the updated expiration date will also be returned in the EXPDATE response parameter.

EXPDATE

110

19 July 2013

Gateway Developer Guide and Reference

Transaction Responses
Processor-specific Response Parameters

As a result, merchants utilizing this feature should check for the presence of the CCUPDATED=Y response parameter, and if it is returned should also check for the presence of the ACCT and EXPDATE response parameters to determine what information has been updated. If you would like to test your integration for this feature, see Testing the Litle Automatic Account Updater Feature on page 90.

Gateway Developer Guide and Reference

19 July 2013

111

Transaction Responses
Processor-specific Response Parameters

112

19 July 2013

Gateway Developer Guide and Reference

Processors 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 113 Elavon Additional Credit Card Parameters on page 119 First Data Merchant Services Nashville, Additional Credit Card Parameters on page 120 First Data Merchant Services North, Additional Credit Card Parameters on page 120 Heartland, Additional Credit Card Parameters on page 121 Litle Additional Credit Card Parameters on page 121 Merchant e-Solutions, Additional Credit Card Parameters on page 123 Paymentech Salem (New Hampshire) Additional Credit Card Parameters for American Express on page 123 PayPal Credit Card Transaction Request Parameters on page 125 SecureNet Additional Credit Card Parameters for American Express on page 130 Vantiv Additional Credit Card Parameters on page 135 WorldPay Additional Credit Card Parameters on page 137

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.
NOT E :

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

Retail Transaction Advice Addendum (for SWIPE transactions)

Field L_DESCn Description (Optional) Description of this line-item (n is a line item number from 1 to 6). Character length and limitations: 19 alphanumeric characters

Gateway Developer Guide and Reference

19 July 2013

113

Processors Requiring Additional Transaction Parameters

American Express Additional Credit Card Parameters

Field L_AMTn

Description (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 (Optional) Quantity of this line-item (n is a line item number from 1 to 6). Character length and limitations: 3 numeric characters

L_QTYn

Internet Transaction Data

Field BILLTOEMAIL Description (Optional) Account holders email address. Character length and limitations: 60 alphanumeric characters (Optional) Account holders telephone number. Character length and limitations: 10 characters (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 (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 (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 (Optional) Account holders IP address. Character length and limitations: 15 alphanumeric and special characters (Optional) Numeric country code of ship-to country. Example: USA: 840. Character length and limitations: 3 characters (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 (Optional) Merchant product SKU. Character length and limitations: 15 alphanumeric characters

BILLTOPHONENUM

PHONETYPE

CUSTHOSTNAME

CUSTBROWSER

CUSTIP

SHIPTOCOUNTRY

SHIPMETHOD

SKU

114

19 July 2013

Gateway Developer Guide and Reference

Processors Requiring Additional Transaction Parameters

American Express Additional Credit Card Parameters

Address Verification Service Parameters

Field BILLTOSTREET Description (Optional) Account holders street address (number and street name). Character length and limitations: 20 characters (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 (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 (Optional) Last name in the shipping address. Character length and limitations: 30 characters (Optional) Shipping street address. Character length and limitations: 30 characters (Optional) Numeric country code of ship-to country. Example: USA: 840. Character length and limitations: 3 alphanumeric characters (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 (Optional) Shipping telephone number. Character length and limitations: 10 alphanumeric characters

BILLTOZIP

BILLTOPHONENUM

SHIPTOLASTNAME

SHIPTOSTREET

SHIPTOCOUNTRY

SHIPTOZIP

SHIPTOPHONENUM

Location Transaction Advice Addendum Parameters

Field MERCHANTNAME Description (Optional) Name of merchant. Character length and limitations: 38 alphanumeric characters (Optional) Merchants 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.

MERCHANTSTREET

Gateway Developer Guide and Reference

19 July 2013

115

Processors Requiring Additional Transaction Parameters

American Express Additional Credit Card Parameters

Field MERCHANTCITY

Description (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 nonnumeric 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 (Optional) Country code of the location where the transaction took place. Character length and limitations: 3 alphanumeric characters (Optional)Merchant-assigned store or location number (or name) that uniquely identifies where the transaction took place. Character length and limitations: 15 alphanumeric characters (Required) American Express-assigned service establishment number used to identify and facilitate payments to merchants. Character length and limitations: 15 alphanumeric characters. (Optional) Merchants 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.
N O TE :

MERCHANTCOUNTRYCODE

MERCHANTLOCATIONID

MERCHANTID

MERCHANTCONTACTINFO

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

116

19 July 2013

Gateway Developer Guide and Reference

Processors Requiring Additional Transaction Parameters

American Express Additional Credit Card Parameters

Transaction Advice Detail Parameters

Field ADDLAMTn Description (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 (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

ADDLAMTTYPEn

Airline Passenger Data Parameters

Field AIR-DEPARTUREDATE Description (Optional) Departure date in the format YYYYMMDD. Character length and limitations: 8 alphanumeric characters (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 (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.
N O TE :

AIR-PASSENGERNAME

AIR-ORIGIN

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.
N O TE :

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, AIRNUMBEROFCITIES 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.

Gateway Developer Guide and Reference

19 July 2013

117

Processors Requiring Additional Transaction Parameters

American Express Additional Credit Card Parameters

Field AIR-ROUTINGCITYn

Description (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 (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_codesAll Character length and limitations: 24 alphanumeric characters

AIR-CARRIERn

AIR-FAREBASIS

(Optional) List discounts associated with the travel. Character length and limitations: 24 alphanumeric characters (Optional) Number of passengers on this trip. Character length and limitations: numeric (Optional) If this is an electronic ticket. The values are: Y = yes N = no Character length and limitations: 1 alphanumeric character (Optional) Code assigned to the travel reservation before the ticket was purchased. Character length and limitations: 15 alphanumeric characters

AIRNUMBEROFPASSENGERS AIR-ISETICKET

AIR-RESERVATIONCODE

American Express Other Parameters

Field BILLTOFIRSTNAME Description (Optional) Account holder's first and last name.
N O TE :

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

118

19 July 2013

Gateway Developer Guide and Reference

Processors Requiring Additional Transaction Parameters

Elavon Additional Credit Card Parameters

Field INVNUM

Description (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 (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. (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.

ORDERDATE

ORDERDATETIME

Elavon Additional Credit Card Parameters

In addition to the core credit card parameters, Elavon (formerly Nova) accepts the parameter described below.
Field RECURRING Description (Optional) Identifies the transaction as recurring. This value does not activate the Payflow Recurring Billing Service API. If the RECURRING parameter was set to Y for the original transaction, then the setting is ignored when forming credit, void, and force transactions. If you subscribe to Payflow Fraud Protection Services: To avoid charging you to filter recurring transactions that you know are reliable, the fraud filters do not screen recurring transactions. To screen a prospective recurring customer, submit the transaction data using PayPal Manager's Manual Transactions page. The filters screen the transaction in the normal manner. If the transaction triggers a filter, then you can follow the normal process to review the filter results. Character length and limitations: 1 alphanumeric character (Y or N)

Gateway Developer Guide and Reference

19 July 2013

119

Processors Requiring Additional Transaction Parameters

First Data Merchant Services Nashville, Additional Credit Card Parameters

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.
Field INVNUM Description (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

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 DESC Description (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.
N O TE :

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

120

19 July 2013

Gateway Developer Guide and Reference

Processors Requiring Additional Transaction Parameters

Heartland, Additional Credit Card Parameters

Field MERCHSVC

Description (Optional) Defaults to the city where the merchant outlet is located for retail and to the merchants 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

Heartland, Additional Credit Card Parameters

In addition to the core credit card parameters, Heartland accepts the parameters described below.
Field INVNUM Description (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.
N O TE :

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 (Optional) Defaults to the city where the merchant outlet is located for retail and to the merchants 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

MERCHSVC

Litle Additional Credit Card Parameters

Field AUTHDATE

Description Required for Force transactions. Authorization date. Character length and limitations: 11alphanumeric characters (Optional) Customer identification. Character length and limitations: 18 alphanumeric characters

CUSTOMERID

Gateway Developer Guide and Reference

19 July 2013

121

Processors Requiring Additional Transaction Parameters

Litle Additional Credit Card Parameters

Field INVNUM

Description (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 (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 (Optional) Merchants website. This information is usually displayed in the account holders statement. Character length and limitations: 40 alphanumeric characters (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 (Optional) Defaults to the city where the merchant outlet is located for retail and to the merchants 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 (Optional) Purchase order number. Character length and limitations: 25 alphanumeric characters (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 (Optional) Second street address. Character length and limitations: 35 alphanumeric characters (Optional) Third street address. Character length and limitations: 35 alphanumeric characters (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 (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

MERCHANTCITY

MERCHANTURL

MERCHDESCR

MERCHSVC

PONUM

REPORTGROUP

BILLTOSTREET2

BILLTOSTREET3

TAXAMT

TAXEXEMPT

122

19 July 2013

Gateway Developer Guide and Reference

Processors Requiring Additional Transaction Parameters

Merchant e-Solutions, Additional Credit Card Parameters

Merchant e-Solutions, Additional Credit Card Parameters

In addition to the core credit card parameters, Merchant e-Solutions accepts the parameters described below.
Field INVNUM Description (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.
N O TE :

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 (Optional) Defaults to the city where the merchant outlet is located for retail and to the merchants 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

MERCHSVC

Paymentech Salem (New Hampshire) Additional Credit Card Parameters for American Express
In addition to the core credit card parameters, Paymentech Salem accepts the parameters to meet American Express statement and reporting requirements described below.

Internet Transaction Data Parameters

Field BILLTOEMAIL Description (Optional) Account holders email address. Character length and limitations: 60 alphanumeric characters (Optional) Account holders telephone number. Character length and limitations: 20 characters (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

BILLTOPHONENUM

PHONETYPE

Gateway Developer Guide and Reference

19 July 2013

123

Processors Requiring Additional Transaction Parameters

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

Field CUSTHOSTNAME

Description (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 (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 (Optional) Account holders IP address. Character length and limitations: 15 alphanumeric and special characters (Optional) Numeric country code of ship-to country. Example: USA: 840. Character length and limitations: 3 alphanumeric characters (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 (Optional) Merchant product SKU. Character length and limitations: 15 alphanumeric and special characters

CUSTBROWSER

CUSTIP

SHIPTOCOUNTRY

SHIPMETHOD

SKU

AVS Parameters
Field BILLTOSTREET Description (Optional) Account holders street address (number and street name). Character length and limitations: 20 characters (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 (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 (Optional) Last name in the shipping address. Character length and limitations: 30 characters

BILLTOZIP

BILLTOPHONENUM

SHIPTOLASTNAME

124

19 July 2013

Gateway Developer Guide and Reference

Processors Requiring Additional Transaction Parameters

PayPal Credit Card Transaction Request Parameters

Field SHIPTOSTREET

Description (Optional) Shipping street address. Character length and limitations: 30 characters (Optional) Numeric country code of ship-to country. Example: USA: 840. Character length and limitations: 3 alphanumeric characters (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 (Optional) Shipping telephone number. Character length and limitations: 10 alphanumeric characters

SHIPTOCOUNTRY

SHIPTOZIP

SHIPTOPHONENUM

Additional Credit Card Parameters for M Record

Field MERCHDESCR Description (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 (Optional) Defaults to the city where the merchant outlet is located for retail and to the merchants 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

MERCHSVC

PayPal Credit Card Transaction Request Parameters

In addition to the core credit card parameters, PayPal accepts the parameters described below.
Parameter AMT Description (Required) Amount (US Dollars) U.S. based currency. AMT=ITEMAMT + TAXAMT + FREIGHTAMT + HANDLINGAMT + INSURANCEAMT - DISCOUNT
N O TE :

You must set CURRENCY to one of the three-character currency codes for any of the supported PayPal currencies. See CURRENCY in this table for details.

Limitations: Must not exceed $10,000 USD in any currency. Nine numeric characters plus decimal (.) character. No currency symbol. Specify the exact amount to the cent using a decimal pointuse 34.00, not 34. Do not include comma separatorsuse 1199.95 not 1,199.95. Nine numeric characters plus decimal.

Gateway Developer Guide and Reference

19 July 2013

125

Processors Requiring Additional Transaction Parameters

PayPal Credit Card Transaction Request Parameters

Parameter CURRENCY

Description (Required) The currency code.

N O TE :

CURRENCY is applicable only to processors that support transaction-level currency.

Limitations: Three characters. BUTTONSOURCE (Optional) Identification code for use by third-party applications to identify transactions. Limitations: 32 alphanumeric characters. (Optional) IP address of payers browser as recorded in its HTTP request to your website. This value is optional but recommended.
N O TE :

CUSTIP

PayPal records this IP address as a means to detect possible fraud.

Limitations: 15-character string in dotted quad format: xxx.xxx.xxx.xxx CAPTURECOMPLETE (Optional) Indicates if this Delayed Capture transaction is the last capture you intend to make. The values are: Y (default) N
N O TE :

If CAPTURECOMPLETE is Y, any remaining amount of the original reauthorized transaction is automatically voided.

Limitations: 12-character alphanumeric string. CUSTOM (Optional) A free-form field for your own use. Limitations: 256-character alphanumeric string. (Optional) Email address of payer. Limitations: 127 alphanumeric characters. (Optional) Your own unique invoice or tracking number. Limitations: 127 alphanumeric characters. (Required if L_COSTn is specified) Sum of cost of all items in this order. ITEMAMT = L_QTY0*LCOST0 + L_QTY1*LCOST1...L_QTYn*L_COSTn Limitations: Nine numeric characters plus decimal (.) character. No currency symbol. Specify the exact amount to the cent using a decimal pointuse 34.00, not 34. Do not include comma separatorsuse 1199.95 not 1,199.95. Limitations: Nine numeric characters plus decimal. (Required if L_TAXAMTn is specified) Sum of tax for all items in this order. TAXAMT=L_QTY0*L_TAXAMT0 + L_QTY1*L_TAXAMT1 +...L_QTYn *L_TAXAMTn
N O TE :

EMAIL

INVNUM

ITEMAMT

TAXAMT

You must set CURRENCY to one of the three-character currency codes for any of the supported PayPal currencies. See CURRENCY in this table for details.

Limitations: Nine numeric characters plus decimal (.) character. No currency symbol. Specify the exact amount to the cent using a decimal pointuse 34.00, not 34. Do not include comma separatorsuse 1199.95 not 1,199.95. Nine numeric characters plus decimal.

126

19 July 2013

Gateway Developer Guide and Reference

Processors Requiring Additional Transaction Parameters

PayPal Credit Card Transaction Request Parameters

Parameter FREIGHTAMT

Description (Optional) Total shipping costs for this order.

N O TE :

You must set CURRENCY to one of the three-character currency codes for any of the supported PayPal currencies. See CURRENCY in this table for details.

Limitations: Nine numeric characters plus decimal (.) character. No currency symbol. Specify the exact amount to the cent using a decimal pointuse 34.00, not 34. Do not include comma separatorsuse 1199.95 not 1,199.95. Nine numeric characters plus decimal. HANDLINGAMT (Optional) Total handling costs for this order.
N O TE :

You must set CURRENCY to one of the three-character currency codes for any of the supported PayPal currencies. See CURRENCY in this table for details.

Limitations: Nine numeric characters plus decimal (.) character. No currency symbol. Specify the exact amount to the cent using a decimal pointuse 34.00, not 34. Do not include comma separatorsuse 1199.95 not 1,199.95. Nine numeric characters plus decimal. DISCOUNT (Optional) Shipping discount for this order. Specify the discount as a positive amount. Limitations: Nine numeric characters plus decimal (.) character. No currency symbol. Specify the exact amount to the cent using a decimal pointuse 34.00, not 34. Do not include comma separatorsuse 1199.95 not 1,199.95. (Optional) Total shipping insurance cost for this order. Limitations: Nine numeric characters plus decimal (.) character. No currency symbol. Specify the exact amount to the cent using a decimal pointuse 34.00, not 34. Do not include comma separatorsuse 1199.95 not 1,199.95. (Optional) Line-item name.
N O TE :

INSURANCEAMT

L_NAMEn

To enable line-item support, send an email from the Primary email address on the account to [email protected]

Character length and limitations: 36 alphanumeric characters. L_DESCn (Optional) Line-item description of the item purchased such as hiking boots or cooking utensils.
N O TE :

To enable line-item support, send an email from the Primary email address on the account to [email protected]

Limitations: 127 alphanumeric characters.

Gateway Developer Guide and Reference

19 July 2013

127

Processors Requiring Additional Transaction Parameters

PayPal Credit Card Transaction Request Parameters

Parameter L_COSTn

Description (Required if L_QTYn is supplied) Cost of the line item. The line-item unit price can be a positive or a negative value but not 0.
N O TE :

To enable line-item support, send an email from the Primary email address on the account to [email protected] You must set CURRENCY to one of the three-character currency codes for any of the supported PayPal currencies. See CURRENCY in this table for details.

N O TE :

Limitations: Nine numeric characters plus decimal (.) character. No currency symbol. Specify the exact amount to the cent using a decimal pointuse 34.00, not 34. Do not include comma separatorsuse 1199.95 not 1,199.95. Nine numeric characters plus decimal. L_QTYn (Required if L_COSTn is supplied) Line-item quantity.
N O TE :

To enable line-item support, send an email from the Primary email address on the account to [email protected]

Limitations: 10-character integer. L_SKUn (Optional) Product number.

N O TE :

To enable line-item support, send an email from the Primary email address on the account to [email protected]

Limitations: 18-characters. L_TAXAMTn (Optional) Line-item tax amount.

N O TE :

To enable line-item support, send an email from the Primary email address on the account to [email protected]

Limitations: Nine numeric characters plus decimal (.) character. No currency symbol. Specify the exact amount to the cent using a decimal pointuse 34.00, not 34. Do not include comma separatorsuse 1199.95 not 1,199.95. MERCHANTSESSIONID (Optional) Your customer Direct Payment session identification token. PayPal records this session token as an additional means to detect possible fraud. Limitations: 64 characters. (Optional) Your URL for receiving Instant Payment Notification (IPN) about this transaction. If you do not specify NOTIFYURL in the request, the notification URL from your Merchant Profile is used, if one exists. Limitations: 2048 alphanumeric characters. (Optional) Description of items the customer is purchasing. Limitations: 127 alphanumeric characters. (Optional) Type of transaction occurrence. The values are: F = First occurrence S = Subsequent occurrence (default) Limitations: One alpha character.

NOTIFYURL

ORDERDESC

RECURRINGTYPE

128

19 July 2013

Gateway Developer Guide and Reference

Processors Requiring Additional Transaction Parameters

PayPal Credit Card Transaction Request Parameters

Parameter BILLTOCITY

Description (Conditional) Bill-to city address. Limitations: 40 alphanumeric characters.

N O TE :

Some merchants maybe required to pass this billing information. Please test your integration first to determine if the billing information fields are required.

BILLTOSTATE

(Conditional) Bill-to state or province address. Limitations: 40 alphanumeric characters.

N O TE :

Some merchants maybe required to pass this billing information. Please test your integration first to determine if the billing information fields are required.

BILLTOCOUNTRY

(Conditional) Bill-to country address. Limitations: 2 alphanumeric characters.

N O TE :

Some merchants maybe required to pass this billing information. Please test your integration first to determine if the billing information fields are required.

SHIPTOSTREET

(Optional) Ship-to street address.

N O TE :

If you pass in any of the ship-to address parameters such as SHIPTOCITY or SHIPTOSTATE, you must pass in the complete set (that is, SHIPTOSTREET, SHIPTOCITY, SHIPTOSTATE, SHIPTOCOUNTRY, and SHIPTOZIP).

Limitations: 30-character string. SHIPTOCITY (Optional) Ship-to city address.

N O TE :

If you pass in any of the ship-to address parameters such as SHIPTOCITY or SHIPTOSTATE, you must pass in the complete set (that is, SHIPTOSTREET, SHIPTOCITY, SHIPTOSTATE, SHIPTOCOUNTRY, and SHIPTOZIP).

Limitations: 40-character string. SHIPTOSTATE (Optional) Ship-to state or province address.

N O TE :

If you pass in any of the ship-to address parameters such as SHIPTOCITY or SHIPTOSTATE, you must pass in the complete set (that is, SHIPTOSTREET, SHIPTOCITY, SHIPTOSTATE, SHIPTOCOUNTRY, and SHIPTOZIP).

Limitations: 10-character string. SHIPTOCOUNTRY (Optional) Ship-to country code.

N O TE :

If you pass in any of the ship-to address parameters such as SHIPTOCITY or SHIPTOSTATE, you must pass in the complete set (that is, SHIPTOSTREET, SHIPTOCITY, SHIPTOSTATE, SHIPTOCOUNTRY, and SHIPTOZIP).

Limitations: Two alpha characters.

Gateway Developer Guide and Reference

19 July 2013

129

Processors Requiring Additional Transaction Parameters

SecureNet Additional Credit Card Parameters for American Express

Parameter SHIPTOZIP

Description (Optional) U.S. ship-to zip code or other country-specific postal code.
N O TE :

If you pass in any of the ship-to address parameters such as SHIPTOCITY or SHIPTOSTATE, you must pass in the complete set (that is, SHIPTOSTREET, SHIPTOCITY, SHIPTOSTATE, SHIPTOCOUNTRY, and SHIPTOZIP).

Limitations: 20-character string.

SecureNet Additional Credit Card Parameters for American Express

In addition to the core credit card parameters, SecureNet accepts the parameters described below to meet American Express reporting and statement requirements.

Retail Transaction Advice Addendum (for SWIPE transactions)

Field L_DESCn L_AMTn Description (Optional) Description of this line-item (n is a line item number from 1 to 6). Character length and limitations: 19 alphanumeric characters (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 (Optional) Quantity of this line-item (n is a line item number from 1 to 6). Character length and limitations: 3 numeric characters

L_QTYn

Internet Transaction Data

Field BILLTOEMAIL Description (Optional) Account holders email address. Character length and limitations: 60 alphanumeric characters (Optional) Account holders telephone number. Character length and limitations: 10 characters (Optional) Telephone company provided ANI information identifier digits indicating the telephone call type. Examples: cellular (61-63), payphone (27). Character length and limitations: 2 alphanumeric characters

BILLTOPHONENUM

PHONETYPE

130

19 July 2013

Gateway Developer Guide and Reference

Processors Requiring Additional Transaction Parameters

SecureNet Additional Credit Card Parameters for American Express

Field CUSTHOSTNAME

Description (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 (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 (Optional) Account holders IP address. Character length and limitations: 15 alphanumeric and special characters (Optional) Numeric country code of ship-to country. Example: USA: 840. Character length and limitations: 3 alphanumeric characters (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

CUSTBROWSER

CUSTIP

SHIPTOCOUNTRY

SHIPMETHOD

AVS Parameters
Field BILLTOSTREET Description (Optional) Account holders street address (number and street name). Character length and limitations: 20 characters (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 (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 (Optional) Last name in the shipping address. Character length and limitations: 30 characters (Optional) Shipping street address. Character length and limitations: 30 characters

BILLTOZIP

BILLTOPHONENUM

SHIPTOLASTNAME

SHIPTOSTREET

Gateway Developer Guide and Reference

19 July 2013

131

Processors Requiring Additional Transaction Parameters

SecureNet Additional Credit Card Parameters for American Express

Field SHIPTOCOUNTRY

Description (Optional) Numeric country code of ship-to country. Example: USA: 840. Character length and limitations: 3 alphanumeric characters (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 (Optional) Shipping telephone number. Character length and limitations: 10 alphanumeric characters

SHIPTOZIP

SHIPTOPHONENUM

Location Transaction Advice Addendum Parameters

Parameter MERCHANTNAME Description (Optional) Name of merchant. Character length and limitations: 38 alphanumeric characters (Optional) Merchants 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. (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 MERCHANTCOUNTRYCODE (Optional) Country code of the location where the transaction took place. Character length and limitations: 3 alphanumeric characters

MERCHANTSTREET

MERCHANTCITY

132

19 July 2013

Gateway Developer Guide and Reference

Processors Requiring Additional Transaction Parameters

SecureNet Additional Credit Card Parameters for American Express

Parameter MERCHANTZIP

Description (Optional) The 5- to 9-digit zip (postal) code excluding spaces, dashes, and nonnumeric 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

Transaction Advice Detail Parameters

Field ADDLAMTn Description (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 (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

ADDLAMTTYPEn

Airline Passenger Data Parameters

Field AIR-DEPARTUREDATE Description (Optional) Departure date in the format: YYYYMMDD. Character length and limitations: 8 alphanumeric characters (Optional) Name of the passenger in the following format with fields separated by a space: surname firstname middleinitial title Character length and limitations: 40 alphanumeric characters (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.
N O TE :

AIR-PASSENGERNAME

AIR-ORIGIN

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.
N O TE :

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

Gateway Developer Guide and Reference

19 July 2013

133

Processors Requiring Additional Transaction Parameters

SecureNet Additional Credit Card Parameters for American Express

Field AIR-NUMBEROFCITIES

Description (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, AIRNUMBEROFCITIES 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. Character length and limitations: numeric, maximum value is 10

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. For a list of airport codes, see http://www.world-airport-codes.com/alphabetical/airport-code/a.html.
N O TE :

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-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_codesAll. Character length and limitations: 5 alphanumeric characters AIR-FAREBASIS (Optional) List discounts associated with the travel. Character length and limitations: 24 alphanumeric characters (Optional) Number of passengers on this trip. Character length and limitations: numeric (Optional) If this is an electronic ticket. Character length and limitations: 1 alphanumeric character (Y or N) (Optional) Code assigned to the travel reservation before the ticket was purchased. Character length and limitations: 15 alphanumeric characters

AIRNUMBEROFPASSENGERS AIR-ISETICKET

AIR-RESERVATIONCODE

134

19 July 2013

Gateway Developer Guide and Reference

Processors Requiring Additional Transaction Parameters

Vantiv Additional Credit Card Parameters

Other Parameters
Field BILLTOFIRSTNAME Description (Optional) Account holder's first and last name.
N O TE :

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 (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: 17 alphanumeric characters (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.

INVNUM

ORDERDATE

Vantiv Additional Credit Card Parameters

Additional Credit Card Parameters
Field MERCHDESCR Description (Optional) Use this parameter to pass in your DBA name and other data describing the transaction. This information will be displayed in the account holder's statement. Character length and limitations: 25 alphanumeric characters

Soft Merchant Descriptor Parameters

Field MERCHANTNAME Description (Optional) Name of merchant. Character length and limitations: 38 alphanumeric characters (Optional) Merchants 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.

MERCHANTSTREET

Gateway Developer Guide and Reference

19 July 2013

135

Processors Requiring Additional Transaction Parameters

Vantiv Additional Credit Card Parameters

Field MERCHANTCITY

Description (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 nonnumeric 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 (Optional) Country code of the location where the transaction took place. Character length and limitations: 3 alphanumeric characters (Optional)Merchant-assigned store or location number (or name) that uniquely identifies where the transaction took place. Character length and limitations: 15 alphanumeric characters (Required) American Express-assigned service establishment number used to identify and facilitate payments to merchants. Character length and limitations: 15 alphanumeric characters. (Optional) Merchants 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.
N O TE :

MERCHANTCOUNTRYCODE

MERCHANTLOCATIONID

MERCHANTID

MERCHANTCONTACTINFO

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

136

19 July 2013

Gateway Developer Guide and Reference

Processors Requiring Additional Transaction Parameters

WorldPay Additional Credit Card Parameters

WorldPay Additional Credit Card Parameters

Field ADDLAMTn

Description (Optional) Detail of a charge, where n is a value from 1 - 5. Use for additional breakdown of the amount. Character length and limitations: 11 alphanumeric characters (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: 18 alphanumeric characters (Optional) Type of terminal. Character length and limitations: numeric characters (Optional) Describes the card input capability. It is the value RFD, which means the card contains a radio frequency identification (RFID) chip for communicating with a point-of-sale device with an RFID receiver. Character length and limitations: alpha characters

ADDLAMTTYPEn

CATTYPE

CONTACTLESS

Gateway Developer Guide and Reference

19 July 2013

137

Processors Requiring Additional Transaction Parameters

WorldPay Additional Credit Card Parameters

138

19 July 2013

Gateway Developer Guide and Reference

TeleCheck Electronic Check Processing

This appendix describes the host-based capture version of the TeleCheck Non-Face-To-Face Check Acceptance (NFTF) services.

TeleCheck NFTF Overview of Services

NFTF offers merchants the convenience of electronic check deposits. When a NFTF transaction is approved by TeleCheck, the manually entered MICR data from the check is electronically converted to an ACH debit and is processed through the ACH Network. The merchant receives funds within two banking days. NFTF includes TeleCheck Internet Check Acceptance (ICA), Checks By Phone (CBP), and Prearranged Deposit Services (NFTF PPD). Each of these products requires a separate Merchant ID also known as a Subscriber ID. See below for more details.

ICA provides merchants with the capability to authorize and electronically settle checks presented by customers over the internet. ICA can be single entry or recurring. This is based on customer's authorization received over the internet. CBP authorizes and electronically settles checks presented over the phone through customer interaction with a merchant call center representative. CBP services are single entry only. Partial debits and recurring entries are not allowable per NACHA guidelines. NFTF prearranged payment and deposit entry (NFTF PPD) may be used for either recurring or non-recurring debits to a customer's account, when the merchant has provided the customer with a written authorization, which the customer has signed or similarly authenticated. Actual payments are facilitated via the internet or via IVR or over the phone. The application type value must be set to PPD. PPD accounts must establish an end date to clearly define terms between customer and merchant, but do not have time period caps.

TeleCheck NFTF Processing Overview

NFTF requirements, processing considerations, and guidelines for processing check payments are described below.

NFTF Requirements
The following requirements must be followed as standard operating procedures to electronically process a NFTF check payment:

A TeleCheck Merchant ID is required on all transactions and is unique to each location.

Gateway Developer Guide and Reference

19 July 2013

139

TeleCheck Electronic Check Processing

TeleCheck NFTF Processing Overview

Dual ID is required for all transactions. For personal checks, it must be MICR data and personal check writer identification such as a drivers license. For company checks, it must be MICR data and Federal Tax ID. In the event that a company does not have a Federal Tax ID, the drivers license can also be used. For ICA and NFTF PPD, the merchant must retain the customers authorization of the transaction for a period of 2 years and, for ICA, prompt the customer to print a copy of this confirmation for their records. The merchant must adhere to all authorization requirements, data elements, legal verbiage, and check return fee requirements. For CBP, the merchant must audio record the customers verbal confirmation of the transaction or provide a written confirmation of the transaction to the customer prior to settlement. In either case, the confirmation must be live; IVR is not acceptable for confirmation. If a merchant chooses audio, the merchant must have the technical capability to retain these recordings for a period of 2 years; else the written confirmation may be substituted and retained for the same time period. The merchant must adhere to all authorization requirements; data elements, legal verbiage, and check return fee requirements. Only select US accounts drawn on U.S. banks participating in the ACH Network are eligible for processing via the ACH Network. TeleCheck Trace ID (TTID) is required for all supplemental messages, change, void, and adjustment transactions. Merchant Trace ID is required for all adjustment transactions. This field allows additional capabilities to be enabled such as Overflow Credits and MIA Duplicate Checking. Change and Void transactions are only allowed within the original Sale processing window. For NFTF, cutoff time is 4:00PM CST (recommend working with 3:30PM CST). Adjustment transactions are electronically allowed within 90 days after the Sale transaction. After the 90 day period, all adjustments must be manually processed. A prompt or process must be in place to identify a check as either personal or company. Duplicate Checking TeleCheck has the ability to detect duplicate sale transactions at the point of sale if sent within a predetermined time limit. Duplicates are identified when a sale inquiry is received with the same amount, MICR number, and check number matching a sale inquiry received within the last 2 minutes. If a duplicate is detected it will return an ineligible response for ACH. The 2nd transaction will also receive an ineligible response for ACH with the same ACH Transaction Status and Response Code as the original sale transaction. The appropriate Application Type value must be sent to TeleCheck to indicate the type of NFTF transaction (ICA, CBP, or NFTF PPD). In the NFTF technical specification several data element fields and features are described as optional. While these are technically optional, meaning that the product can be technically implemented with or without them, TeleCheck may require the merchant to code to one or more of these optional items based on the agreed upon contractual terms. The merchant may need to account for and enable additional data element fields and product features in their system(s) and in communications to TeleChecks Authorization

140

19 July 2013

Gateway Developer Guide and Reference

TeleCheck Electronic Check Processing

TeleCheck NFTF Processing Overview

System. Various optional data elements throughout each of the message packets could be affected by this requirement.

First Data Gateway Partners, External Gateway vendors, First Data Platforms, and the Global Gateway Router (GGR) that route merchant transactions to TeleCheck via this specification must code for all fields, features, and functionality available in this specification. Nothing is optional for these partners. Additionally, these partners are required to maintain their NFTF specification as new revisions and addendums become available.

NFTF Processing Considerations

TeleCheck and the Merchant must determine any of the following additional optional features during contract negotiations.

MIA Duplicate Checking TeleCheck has the ability to detect duplicate adjustment transactions in back end processes. Adjustments can be submitted up to 90 days after the original Sale transaction. While multiple adjustment transactions are allowed for a given sale transaction, each adjustment transaction must have a unique merchant trace ID. Duplicates are detected when an adjustment transaction is submitted that has the same merchant trace ID as a previously submitted adjustment transaction. If a duplicate adjustment is detected, and the original adjustment was accepted by TeleCheck, the duplicate will also be accepted. The duplicate transaction will then be filtered out by TeleChecks back end settlement processes.

NFTF Guidelines
The following guidelines should be followed when adhering to the above NFTF Requirements to electronically process a check payment:

Fields marked as Required are required to process an electronic transaction. Not all fields are required by every merchant. Unused fields should be completely omitted from the message. Each field is variable in length (justification and fillers are not used). The order of tagged fields from the POS and from the TeleCheck host are not significant. Fields must not have any hard-coded data values. The transaction number increments on every attempt.

Message formats outline fields (tags) that are required, not required, or conditional to the Sale, Status, and Adjustment Inquiry packets. Message Types:

Merchant Authorization Message and the TeleCheck Authorization Response Message Merchant Delayed Capture Message and the TeleCheck Delayed Capture Response Message

Gateway Developer Guide and Reference

19 July 2013

141

TeleCheck Electronic Check Processing

TeleCheck Parameters

Transaction flow Method Messages sent from the Merchant to TeleCheck are authorization messages. Messages sent from TeleCheck to the Merchant are Response messages. The sale transaction process is often referred to as a 2-part hand-off. The process begins with the merchants Authorization message. TeleCheck responds with an Authorization response message indicating whether the transaction is approved and whether the check is eligible for conversion (whether check conversion will be offered). The Merchant then responds with a Delayed Capture message, acknowledging receipt of TeleChecks sale response, and indicating whether electronic check conversion was accepted. TeleCheck completes the transaction with a Delayed Capture response message confirming receipt of the merchants status inquiry message.

TeleCheck Parameters
Parameters used for processing electronic checks through TeleCheck are described in this section.

142

19 July 2013

Gateway Developer Guide and Reference

TeleCheck Electronic Check Processing

TeleCheck Parameters

Required TeleCheck Parameters

Field USER

Description (Required) Case-sensitive login ID for the Gateway account that you created while registering for the account. In the future, each account will allow multiple users. This parameter will specify the user. Character length and limitations: 64 alphanumeric characters (Required) Case-sensitive Vendor ID that you created while registering for the account. Character length and limitations: 64 alphanumeric characters (Required) The authorized PayPal Reseller that registered you for the Gateway service provided you with a Partner ID. If you registered yourself, use PayPal. This parameter is case sensitive. Character length and limitations: 64 alphanumeric characters (Required) Case-sensitive 6- to 32-character password that you created while registering for the account. Character length and limitations: 32 alphanumeric characters (Required) This is the transaction amount (default U.S. dollars). The transaction amount should always specify a decimal, and the exact amount to the cent (for example, 34.00, instead of 34). Do not include comma separators in the amount. Use 1199.95 not 1,199.95. Character length and limitations: 7 numeric characters, U.S. dollars only It is one of the following values: I Internet Check Acceptance (ICA) provides the capability to authorize and electronically settle checks over the intenet. P Checks By Phone (CBP) provides the capability to authorize and electronically settle checks over the phone. D Prearranged Deposit Services (PPD) debits the customers account provided the customer has previously accepted a written authorization. (Required) Account holders city. Character length and limitations: 30 alphanumeric characters Account holders country. You are required to pass this value when AUTHTYPE=I. Character length and limitations: 2 alphanumeric characters Account holders first name as it appears on the check. You are required to pass this value when CHKTYPE=C. Character length and limitations: 30 alphanumeric characters (Required) Account holders last name as it appears on the check. Character length and limitations: 30 alphanumeric characters

VENDOR

PARTNER

PWD

AMT

AUTHTYPE

BILLTOCITY

BILLTOCOUNTRY

BILLTOFIRSTNAME

BILLTOLASTNAME

Gateway Developer Guide and Reference

19 July 2013

143

TeleCheck Electronic Check Processing

TeleCheck Parameters

Field BILLTOPHONENUM

Description (Required) Account holders telephone number. Character length and limitations: 10 numeric characters. This value may not contain spaces or non-numeric characters. (Required) Account holders state. Character length and limitations: 2 alphanumeric characters (Required) Account holders street address. Character length and limitations: 50 alphanumeric characters (Required) Account holders postal code (called ZIP code in the USA). Do not use spaces, dashes, or non-numeric characters. Character length and limitations: 11 alphanumeric characters (Required) Account holders next unused (available) check number. Character length and limitations: 7 numeric characters (Required) Check type. It is one of the following values: P The check is a personal check (default). If CHKTYPE=P, you are required to pass a value for either DL or SS as an identifier. C The check is a company check. If CHKTYPE=C, you are required to pass the Federal Tax ID for SS. Character length and limitations:1 alphanumeric character Account holders IP address. You are required to pass this value when AUTHTYPE=I. Character length and limitations: 15 alphanumeric characters (Required) Drivers license number. If CHKTYPE=P, you are required to pass a value for either DL or SS as an identifier. The format of the drivers license information is XXnnnnnnnn where: XX = State code nnnnnnnn = Drivers license number Character length and limitations: 33 alphanumeric characters (Required) Account holders e-mail address. You are required to pass this value when AUTHTYPE=I. Character length and limitations: 100 alphanumeric characters (Optional) Check invoice number. Character length and limitations: 9 alphanumeric characters (Required) Magnetic ink check reader. The value is the entire line of numbers at the bottom of all checks. It includes the transit number, account number, and check number. Character length and limitations: 65 numeric characters

BILLTOSTATE

BILLTOSTREET

BILLTOZIP

CHKNUM

CHKTYPE

CUSTIP

DL

BILLTOEMAIL

INVNUM

MICR

144

19 July 2013

Gateway Developer Guide and Reference

TeleCheck Electronic Check Processing

Testing TeleCheck Transactions

Field SS

Description Account holders social security number. You are required to pass a value for SS when a value for CHKTYPE is passed: If CHKTYPE=P, you are required to pass a value for either DL or SS as an identifier. If CHKTYPE=C, you are required to pass the Federal Tax ID. Character length and limitations: 35 alphanumeric characters (Required) Method of payment. Use only the value K (electronic check). Character length and limitations: 1 alphabetic character (Required) Type of transaction that should be processed. It is one of the following values: A The transaction is an Authorization. D The transaction is a Delayed Capture. V The transaction is a Void. I The transaction is an Inquiry. Character length and limitations: 1 alpha character

TENDER

TRXTYPE

Testing TeleCheck Transactions

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

Example Test Transaction

This is the authorization request and response.
TRXTYPE=A&TENDER=K&PARTNER=partner&USER=user&VENDOR=vendor&PWD=pwd&AMT=35.0 0&BILLTOSTREET=1234 Main&BILLTOCITY=Buffalo&DL=CA123456&CHKNUM=1001&BILLTOE [email protected]&MICR=3333333333&AUTHTYPE=I&INVNUM=12345&BILLTOFIRSTNAME=S ally&BILLTOLASTNAME=Smith&BILLTOSTATE=CA&BILLTOZIP=95050&BILLTOCOUNTRY=US&C USTIP=10.15.5.23&BILLTOPHONENUM=9876542143&VERBOSITY=HIGH RESULT=0&PNREF=EQ RB8A32CD69&RESPMSG=Approved&AUTHCODE=12&TRACEID=1234567890&ACHSTATUS=A&HOST CODE=07&TRANSTIME=2012-0209 15:23:37&BILLTOFIRSTNAME=Sally&BILLTOLASTNAME=Smith&AMT=35.00&CARDTYPE=P

This is the delayed capture request and response.

TRXTYPE=D&TENDER=K&PARTNER=partner&USER=user&VENDOR=vendor&PWD=pwd&ORIGID=E QRB8A32CD69&VERBOSITY=HIGH RESULT=0&PNREF=EQRB8A32CD6A&RESPMSG=Approved&AUTHCODE=00&TRACEID=1234567890 &ACHSTATUS=A&HOSTCODE=07&TRANSTIME=2012-02-09 15:24:22

Gateway Developer Guide and Reference

19 July 2013

145

TeleCheck Electronic Check Processing

Preparing for TeleCheck Production Transactions

MICR values for testing

You may view a complete list of TeleCheck response codes at Sale Response Code Values on page 147
MICR 3333333333 1111111111 2222222222 HOSTCODE 07 08 88 TeleCheck Result Approved Rejected (negative data) Rejected Code 3 (Risk)

Preparing for TeleCheck Production Transactions

Before going into production with your check integration, you must certify your storefront with TeleCheck. To begin the certification process, send an e-mail to [email protected]. Be sure to include the following information:

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

The certification process usually takes 2-3 days. Use the host address of the live server described in Host URL Addresses on page 50.

Responses to TeleCheck Transactions

When a transaction finishes, PayPal returns a response string made up of name-value pairs. For example:
RESULT=0&PNREF=VXYZ01234567&HOSTCODE=000500&RESPMSG=Approved

TeleCheck transaction response values are described in the table below.

Transaction Responses Common to All Tender Types

Field RESULT Description The outcome of the attempted transaction. A result of 0 (zero) indicates the transaction was approved. Any other number indicates a decline or error. Character length and limitations: numeric, variable number of characters PayPal Reference ID, a unique number that identifies the transaction. Character length and limitations: 12 alphanumeric characters

PNREF

146

19 July 2013

Gateway Developer Guide and Reference

TeleCheck Electronic Check Processing

Response Code Values

Field HOSTCODE

Description TeleCheck's response code representing the results of the transaction authorization attempt. Character length and limitations: 6 numeric characters A descriptive message associated with decline or error result values. Character length and limitations: alphanumeric, variable number of characters

RESPMSG

Response Code Values

For your service, below is a complete list of possible Response Codes. Depending upon the merchants risk parameters and service type, some of these may not apply. Please confirm applicable codes with TeleCheck's Merchant Boarding and Certification group.
NOT E :

Merchants should establish policies and procedures for each applicable response code. For example, if a clerk enters a transaction and receives Response Code 27, they should retry the transaction. If, after entering the item a second time they receive a Response Code 27 again, the merchant may choose to cancel or terminate the transaction and a) retry the transaction b) call TeleCheck Live Operator Authorization Center, or c) request another form of payment from the check writer.

Sale Response Code Values

Sale Approval Responses Code 07 Description Approved Merchant Action No action needed.

Sale Decline Responses Code 08 73 88 25 Description Rejected (Negative Data) Lost or Stolen check Rejected Code 3 (Risk) Ineligible ACH Not Offered
NOT E :

Merchant Action Ask for other form of payment or decline sale to customer. Ask for other form of payment or decline sale to customer. Ask for other form of payment or decline sale to customer. Ask for other form of payment.

Do NOT use the verbiage decline this is not a true decline.

Gateway Developer Guide and Reference

19 July 2013

147

TeleCheck Electronic Check Processing

Response Code Values

Sale Referral Responses Code 09 69 Description Risk Referral requested Call Center Merchant Action Contact TeleCheck. Contact TeleCheck.

Sale Error Responses Code 46 49 98 27 78 97 Description Merchant setup does not allow this type of transaction Processor Not Available Invalid MICR Data Invalid Value for Field Invalid RT (Routing/Bank Number) Unable to Process (Time Out) Re-send message later. Re-send message later. Merchant Action

Adjustment Code Values

Adjustment (Refund/Change/Void) Responses Code 26 Description Merchant allowed to send full/partial adjustments/refunds without transaction errors Merchant setup does not allow this type of transaction Original transaction was not approved Refund or partial amount is greater than the original sale amount Unable to locate original transaction (TCK Trace ID) Merchant Action No action needed

46 79 80 81

Adjustment cannot be processed by TeleCheck Adjustment cannot be processed by TeleCheck Adjustment cannot be processed by TeleCheck Adjustment cannot be processed by TeleCheck

Response Codes For Status Response Packets

Response Codes for Status Response Packets Code OK Description Inquiry (POS system) Packet was accepted and successfully processed by TeleCheck

148

19 July 2013

Gateway Developer Guide and Reference

TeleCheck Electronic Check Processing

TeleCheck Authorization Requirements

Code ACK NAK 49 97 27

Description Inquiry Packet was accepted by the TeleCheck Host Inquiry Packet was not successfully processed by TeleCheck (general error) Inquiry Packet was not successfully processed by TeleCheck (scheduled maintenance) Inquiry Packet was not successfully processed by TeleCheck (timeout) Inquiry Packet was not successfully processed by TeleCheck (invalid data)

TeleCheck Authorization Requirements

With the TeleCheck Non Face-To-Face (NFTF) Host Based Capture Service, the merchant is responsible for handling all front-end aspects of the point of sale, including displaying the appropriate disclosures to the customer. TeleCheck will provide form language for the merchant to use.
NOT E :

It is the merchants responsibility to ensure that they have the most current language from TeleCheck. TeleCheck will send out a Service Notice when updated language or system changes are required. Additionally, the Merchant should be familiar with NACHA, FCRA and Reg. E compliance requirements.

There are two different situations during which the merchant must display legal language:

Authorization Sales Consent The language varies slightly between the Internet Check Acceptance and Checks By Phone services.

Authorization Sales Decline The language is identical for Internet Check Acceptance and Checks By Phone services.

Authorization Sales Consent

With the Non Face-To-Face Host Based Capture Service, the merchant is responsible for handling all front-end aspects of the point of sale, including displaying the appropriate disclosures to the customer. TeleCheck will provide form language for the merchant to use.
Internet Check Acceptance Authorizations

At the end of the check out process, the merchant must display consent language for the customer to accept prior to submitting the authorization request as follows: Internet Check Acceptance Authorization Consent Required Language FULL DEBIT By entering my account number above and clicking Authorize, I authorize my payment to be processed as an electronic funds transfer or draft drawn from my account. If the payment is returned unpaid, I authorize you or your service provider to collect the payment and my states

Gateway Developer Guide and Reference

19 July 2013

149

TeleCheck Electronic Check Processing

TeleCheck Authorization Requirements

return item fee by electronic funds transfer(s) or draft(s) drawn from my account. Click here to view your states returned item fee. If this payment is from a corporate account, I make these authorizations as an authorized corporate representative and agree that the entity will be bound by the NACHA Operating Rules. PARTIAL SHIPMENTS & PARTIAL DEBITS By entering my account number above and clicking Authorize, I authorize my payment to be processed as an electronic funds transfer or draft drawn from my account. If my full order is not available at the same time, I authorize partial debits to my account, not to exceed the total authorized amount. The partial debits will take place upon each shipment of partial goods. If any of my payments are returned unpaid, I authorize you or your service provider to collect the payment and my states return item fee by electronic fund transfer(s) or draft(s) drawn from my account. Click here to view your states returned item fee. If this payment is from a corporate account, I make these authorizations as an authorized corporate representative and agree that the entity will be bound by the NACHA Operating Rules. Internet Check Acceptance Recurring Payments (WEB R) By entering my account number above and clicking Authorize, I authorize my payments to be processed as electronic funds transfers or drafts drawn from my account. {INSERT INFORMATION ON PAYMENT AMOUNT, TIMING, ETC.} If any of my payments are returned unpaid, I authorize you or your service provider to collect the payment and my states return item fee by electronic fund transfer(s) or draft(s) drawn from my account. Click here to view your states returned item fee. If this payment is from a corporate account, I make these authorizations as an authorized corporate representative and agree that the entity will be bound by the NACHA Operating Rules. This authorization is to remain in full force and effect until {NAME OF MERCHANT} has received written notification from me of my termination in such time and manner as to afford {NAME OF MERCHANT} a reasonably opportunity to act on it. This text, Click here to view your states returned item fee, in the consent language above represents a link to the state fee table. TeleCheck has posted a table of current state returned check fees at http://www.firstdata.com/support/telecheck_returned_check/returned_check_fees.htm. The merchant should link directly to the TeleCheck-hosted URL provided above. State fees are updated on a regular basis and linking to a TeleCheck-hosted page will minimize the number of maintenance updates required. The merchant may choose how to display the state fees. Suggestions include a new pop-up window, a full browser window, or directly on the checkout page.
Checks By Phone Service Authorizations

At the end of the check out process, the customer service agent must read the consent language to the consumer and, either audio record the consumers authorization or send a written notification of the authorization and the transaction to the consumer prior to settlement of the transaction. The consent language for the customer to accept prior to submitting the payment authorization request is as follows: Checks By Phone Authorization Consent Required Language FULL DEBIT

150

19 July 2013

Gateway Developer Guide and Reference

TeleCheck Electronic Check Processing

TeleCheck Authorization Requirements

Today (insert todays date), Id like to confirm that you, (insert first and last name), are authorizing a payment in the amount of (insert amount) to be processed as an electronic funds transfer or draft drawn from your account. Do you agree? If your payment is returned unpaid, you authorize us or our service provider to collect the payment and your states return item fee of (insert state returned item fee) by electronic funds transfer(s) or draft(s) drawn from your account. Do you agree and authorize the payment? The merchant should link directly to the TeleCheck-hosted URL provided above. State fees are updated on a regular basis and linking to a TeleCheck-hosted page will minimize the number of maintenance updates required. The merchant may choose how you want to display the state fees. Suggestions include a new pop-up window, a full browser window, or directly on the checkout page.
NOT E :

For an additional fee, TeleCheck can send the written notification of the authorization and transaction to the consumer on the merchants behalf.

Prearranged Payments and Deposits Authorizations (PPD)

Payments are facilitated, not authorized. Authorization is via paper from consumer to merchant. PPD Authorization Requirements:

Must be face-to-face, in writing and signed. Must clearly and conspicuously state it terms, such as consumer name, payment amount, payment timing (if recurring) and bank routing/account information. Must also provide that authorization may be revoked in the manner specified in the authorization. Customer must be provided a copy.

Language Sample for PPD

By providing a check as payment, I authorize you to use information from my check to make a one-time electronic funds transfer (EFT) or draft from my account, or to process the payment as a check transaction. When you use information from my check to make an EFT, funds may be withdrawn from my account as soon as the same day my payment is received, and I will not receive my check back from my financial institution. The account referenced above is a (check one): Consumer account Business account If my payment is returned unpaid, I authorize you or your service provider to collect my payment and my states return fee set forth below by EFT(s) or draft(s) from my account. I understand that I can revoke this authorization by sending written notice to _____ in such time and manner as to afford ____ a reasonable opportunity to act on it. If this payment is from a corporate owned account, I make these authorizations as an authorized corporate representative and agree that the entity will be bound by the NACHA Operating Rules. Returned Check Fees: TeleCheck has posted a table of current state returned check fees at http://www.firstdata.com/support/telecheck_returned_check/returned_check_fees.htm. The

Gateway Developer Guide and Reference

19 July 2013

151

TeleCheck Electronic Check Processing

TeleCheck Authorization Requirements

merchant should link directly to the TeleCheck-hosted URL provided above. State fees are updated on a regular basis and linking to a TeleCheck-hosted page will minimize the number of maintenance updates required. The merchant may choose how to display the state fees. Suggestions include a new pop-up window, a full browser window, or directly on the checkout page.
AK $30HI $30MN $30_ OH $30^^ VI $20 AL $30 IA $30 MO $25 OK $25 VT $25 AR $25 ID $20MS $40 OR $25 WA $30_ AZ $25 IL $25MT $30 PA $30 WI $25CA $25 IN $20NC $25 PR $10 WV $25 CO $20KS $30 ND $30 RI $25 WY $30 CT $20KY $50 NE $35 SC $30 DE $40 LA $25^ NH $25 SD $40 DC $25 MA $25 NJ $30 TN $30FL $25_ MD $35 NM $30 TX $30~ GA $30^ ME $25 NV $25 UT $20GU $20 MI $25 NY $20VA $50

Authorization Sales Decline/Error

Authorization requests can fail for a number of reasons, ranging from missing or invalid fields to business decisions based on risk assessment. These different scenarios need to be handled differently by the merchant, and require different legal language to be displayed to the customer. Sale Decline Required Language We are sorry that we cannot accept your check at this time. Our decision is based, in whole or in part, on information provided to us by TeleCheck. We encourage you to call TeleCheck at 1-800.366.2425 or write TeleCheck Customer Care at P.O. Box 4513, Houston, TX 772104513. Please provide TeleCheck your driver's license number and the state where it was issued, and the complete banking numbers printed on the bottom of your check. Under the Fair Credit Reporting Act, you have the right to a free copy of your information held in TeleCheck's files within 60 days from today. You may also dispute the accuracy or completeness of any information in TeleCheck's consumer report. TeleCheck did not make the adverse decision to not accept your payment item and is unable to explain why this decision was made. Sale Error Responses We are unable to process this transaction with the payment information provided. Please use a different form of payment at this time.

152

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

PayPal Payment Services supports passing Purchasing Card Level 2 information (such as purchase order number, tax amount, and charge description) in the settlement file. If additional required invoice information and line-item details are included in the transaction, PayPal formats Purchasing Card Level 3 information in an appropriate format, for example, EDI (Electronic Data Interchange) 810 format as required by American Express during settlement processing. Please contact your merchant bank to determine which parameters are required to obtain the best rate for level 2 or level 3 type transactions. If in doubt, we recommend you send all the level 2 and level 3 fields specified below for your processor.

About Purchasing Cards

The procurement process uses purchasing cards for a number of reasons. Purchasing cards:

Eliminate paper-based order systems and associated costs Improve control and accountability through itemized statements Foster better risk controls through spending limits and buying from approved vendors Reduce administrative overhead by empowering employees to make small purchases Enable enterprises to negotiate better contract pricing and discounts with suppliers by using vendor detail reports

To promote acceptance and usage of purchasing card programs, card issuers have established incentive rates for merchants. The incentive rates are available to merchants who comply at transaction processing Level 2 or Level 3. Transactions that comply at transaction processing Level 1 qualify as normal credit card transactions.
NOT E :

Card issuing institutions perform strict data verification on the enhanced data that merchants submit with Level 2 or Level 3 transactions. Issuers may charge stiff penalties when fields contain either inaccurate or filler data. Only transactions that contain accurate data are eligible for the incentive rates.

About Program Levels

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

Gateway Developer Guide and Reference

19 July 2013

153

Submitting Purchasing Card Level 2 and 3 Transactions

About American Express Purchasing Card Transactions

Level Level 1

Description Function as normal credit cards and are authorized and associated with normal transaction data in authorization and settlement. Any merchant who accepts credit cards supports this level.. Additional data regarding sales tax, customer code, purchase order number, invoice number are captured at the point of sale. In most cases, this information is combined with the merchant's tax ID number, state, and postal code data and is then passed through during settlement. For some processors and banks, however, a Level 2 authorization may include some of this data. Significant additional information such as line items, product codes, item descriptions, unit price, unit quantities, and ship-to postal data are added to the Level 2 data to provide optimal reporting to buyers and sellers. Settlement transactions typically carry Level 3 data.

Level 2

Level 3

Level 2 and Level 3 data is generally considered non-financial data. Lack of adequate data may cause a transaction to be downgraded. PayPal generally requires up to Level 2 information in an authorization transaction followed by additional Level 3 data in the associated delayed capture transaction. A sale transaction should include all Level 3 data since it is authorized and later settled.

Accepted BIN Ranges

Visa, MasterCard, and American Express publish specific Bank Identification Number (BIN) ranges for purchasing cards. Sometimes the processor determines whether a card is a purchasing card, for example, TSYS Acquiring Solutions. In other cases, the Gateway makes the determination based on the BIN range (for example, FDMS South and American Express).

About American Express Purchasing Card Transactions

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

Supported Transaction Types

You can submit Level 3 parameters with delayed capture, sale, credit, or force transactions. Level 3 data in authorization transactions is ignored. The Gateway decides whether a transaction meets Level 3 requirements during authorization. Level 3 data is passed to the American Express processor only during settlement.

154

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

About American Express Purchasing Card Transactions

Avoiding Downgrade
If a transaction uses the purchasing card BIN range (see Accepted BIN Ranges on page 156) and contains a line item but does not include all mandatory Level 3 parameters, the transaction succeeds but is processed as Level 2 or Level 1 during settlement (depending on which data was passed). For downgraded transactions, with the VERBOSITY parameter set to HIGH, the ADDLMSGS field returns a message like the following:
Features not processed: PCARD L3 (missing or invalid: InvoiceNumber RequestorName)

or
Features not processed: PCARD L3 (line item 3 missing: Description)

For details on VERBOSITY, see VERBOSITY: Processor-Specific Transaction Results on page 217

Submitting Successful Level 3 Transactions

If a transaction uses the purchasing card BIN range, contains all mandatory Level 3 fields, and has at least 1 line item (with all mandatory line item fields), the Gateway flags it as Level 3.

Edit Check
The Gateway performs an edit check on the transaction's amount fields to ensure that all line item and tax amounts balance. If the edit check fails, the transaction fails with Result 4: Invalid Amount. To pass the edit check, the following relationship must be true:
Transaction Amount = Total Tax Amount + Total Freight Amount + Total Handling Amount + Total Line Item Amount. Transaction Amount Total Tax Amount Total Freight Amount Total Handling Amount Total Line Item Amount Total amount for the transaction, AMT TAXAMT FREIGHTAMT, or, if not present, the summation of L_FREIGHTAMTn for all line items HANDLINGAMT, or, if not present, the summation of L_HANDLINGAMTn for all line items Summation of L_QTYn * L_COSTn for all line items (n as the line item number). For example, if there are 2 line items, then the Total Line Item Amount would be (LQTY1*LCOST1) + (LQTY2*LCOST2)

Gateway Developer Guide and Reference

19 July 2013

155

Submitting Purchasing Card Level 2 and 3 Transactions

American Express Purchasing Card Transaction Processing

Accepted BIN Ranges

The following BIN ranges are accepted for American Express Level 2 and Level 3 transactions: 37326 37429 37857 37859 37873 37965

American Express Purchasing Card Transaction Processing

The American Express supports Level 2 transaction data.
NOT E :

Most merchants in the United States follow American Express reporting and statement requirements.International merchants now follow these requirements as well, but there maybe a few exceptions. If you are not sure, contact your American Express Representative.

American Express Level 2 Parameters for American Express

The parameters to meet American Express reporting and statement requirements are described in the following tables.
CPC Level 2 Transaction Advice Addendum Parameters Field PONUM Description (Required) Purchase order number. Character length and limitations: 17 alphanumeric characters (Optional) Ship-to postal code (called zip code in the USA). This field must contain one of the following values: Zip code of the destination where the merchandise is to be shipped (If the above is not available) Zip code of the location where the merchant executed the transaction Character length and limitations: 15 alphanumeric characters TAXAMT (Optional) Total tax amount. Must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: 12 numeric characters (Optional) Description of this line item; if not provided, DESC1 (if present) is used. Character length and limitations: 140 alphanumeric characters

SHIPTOZIP

L_DESC1

156

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

American Express Purchasing Card Transaction Processing

Field L_AMT1

Description (Optional) Charge for this line item. Must include a decimal and be exact to the cent (42.00, not 42) and exclude comma separators (1234.56 not 1,234.56). Character length and limitations: 12 numeric characters (Optional) Quantity of this line item. Character length and limitations: 3 numeric characters (Optional) Description of this line item; if not provided, DESC2 (if present) is used. Character length and limitations: 40 alphanumeric characters (Optional) Charge for this line item. Must include a decimal and be exact to the cent (42.00, not 42) and exclude comma separators (1234.56 not 1,234.56). Character length and limitations: 12 numeric characters (Optional) Quantity of this line item. Character length and limitations: 3 numeric characters (Optional) Description of this line item; if not provided, DESC3 (if present) is used. Character length and limitations: 40 alphanumeric characters (Optional) Charge for this line item. Must include a decimal and be exact to the cent (42.00, not 42) and exclude comma separators (1234.56 not 1,234.56). Character length and limitations: 12 numeric characters (Optional) Quantity of this line item. Character length and limitations: 3 numeric characters (Optional) Description of this line item; if not provided, DESC4 (if present) is used. Character length and limitations: 30 alphanumeric characters (Optional) Charge for this line item. Must include a decimal and be exact to the cent (42.00, not 42) and exclude comma separators (1234.56 not 1,234.56). Character length and limitations: 12 numeric characters (Optional) Quantity of this line item. Character length and limitations: 3 numeric characters Location Transaction Advice Addendum Parameters

L_QTY1

L_DESC2

L_AMT2

L_QTY2

L_DESC3

L_AMT3

L_QTY3

L_DESC4

L_AMT4

L_QTY4

Field MERCHANTNAME

Description (Optional) Name of merchant. Character length and limitations: 38 alphanumeric characters (Optional) Merchants 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.

MERCHANTSTREET

Gateway Developer Guide and Reference

19 July 2013

157

Submitting Purchasing Card Level 2 and 3 Transactions

American Express Purchasing Card Transaction Processing

Field MERCHANTCITY

Description (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 nonnumeric 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 (Optional) Country code of the location where the transaction took place. Character length and limitations: 3 alphanumeric characters (Optional)Merchant-assigned store or location number (or name) that uniquely identifies where the transaction took place. Character length and limitations: 15 alphanumeric characters (Required) American Express-assigned service establishment number used to identify and facilitate payments to merchants. Character length and limitations: 15 alphanumeric characters. (Optional) Merchants 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.
N O TE :

MERCHANTCOUNTRYCODE

MERCHANTLOCATIONID

MERCHANTID

MERCHANTCONTACTINFO

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

158

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

American Express Purchasing Card Transaction Processing

Transaction Advice Detail Parameters Field ADDLAMTn Description (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 (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

ADDLAMTTYPEn

Example American Express Level 2 Transaction Parameter String

TRXTYPE=S&ACCT=372449635311003&AMT=20.06&BILLTOCITY=Mountain View&DESC1=des c1&DESC2=desc2&DESC3=desc3&DESC4=FRT10.00&EXPDATE=1215&BILLTOFIRSTNAME=Card holder first name&BILLTOLASTNAME=Cardholder last name&PARTNER=PayPal&PONUM= 12345&PWD=pwd&SHIPTOZIP=94045&BILLTOSTATE=CA&BILLTOSTREET=123 Main St.&TEND ER=C&USER=user&BILLTOZIP=123451234

American Express Level 3 Parameters

American Express supports Level 3 transaction data. PayPal provides the Merchant Registration data values: Supplier Name, Supplier City, Supplier State, Supplier Postal code, Merchant No, and Federal Tax ID. The merchant provides the values listed in the the following table.
American Express Level 3 Parameters Field INVNUM Description (Optional) Purchase order number. Character length and limitations: 1 to 9 alphanumeric characters (Required) Authorization code. It is passed transparently for delayed capture. Use only with voice authorized force capture transactions. (Required) Requester name. Character length and limitations: 1 to 40 alphanumeric characters (Required) Cardmember reference number. Character length and limitations: 1 to 17 alphanumeric characters

AUTHCODE REQNAME

PONUM

Gateway Developer Guide and Reference

19 July 2013

159

Submitting Purchasing Card Level 2 and 3 Transactions

American Express Purchasing Card Transaction Processing

Field SHIPTOZIP

Description (Required) Ship-to postal code (called zip code in the USA). This field must contain one of the following values: Zip code of the destination where the merchandise is to be shipped (If the above is not available) Zip code of the location where the merchant executed the transaction Character length and limitations: 5 to 6 alphanumeric characters (Optional) Invoice date. Defaults to transaction date if not present. Character length and limitations: 8 alphanumeric characters, in the YYYYMMDD format (Required) Total transaction amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56).
NOTE:

INVOICEDATE

AMT

American Express Level 3 processing requires that this parameter have a maximum field length of 8 for Level 3 processing. .

Character length and limitations: 1 to 8 alphanumeric characters TAXAMT (Required) Total tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: 1 to 6 numeric characters (Optional) Charge description. Defaults to NO. Character length and limitations: 1 to 40 alphanumeric characters (Optional) Total freight amount. Character length and limitations: 1 to 15 alphanumeric characters (Optional) Total handling amount. Character length and limitations: 1 to 15 alphanumeric characters Payflow SDK: XMLPay: Item.Quantity (Required) Quantity invoiced. Character length and limitations: 1 to 10 numeric characters (Required) Unit of measure. Character length and limitations: 2 alphanumeric characters (Required) Unit price. Character length and limitations: 1 to 15 numeric characters (Required) Description of the item. Character length and limitations: 1 to 80 alphanumeric characters (Required) Suppliers catalog number. Character length and limitations: 1 to 20 alphanumeric characters (Required) Cost center number Character length and limitations: 1 to 30 alphanumeric characters

DESC

FREIGHTAMT

HANDLINGAMT L_QTYn

L_UOMn L_COSTn L_DESCn L_CATALOGNUMn L_COSTCENTERNUMn

160

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

American Express Purchasing Card Transaction Processing

Field L_PRODCODEn L_UPCn L_TAXAMTn L_FREIGHTAMTn L_HANDLINGAMTn L_TRACKINGNUMn L_PICKUPSTREETn L_PICKUPCITYn L_PICKUPSTATEn L_PICKUPZIPn L_PICKUPCOUNTRYn L_UNSPSCCODEn

Description (Optional) The items supplier stock keeping unit (SKU) number. Character length and limitations: 1 to 30 alphanumeric characters (Optional) The items universal product code (UPC). Character length and limitations: 1 to 30 alphanumeric characters (Optional) Item tax amount. Character length and limitations: 1 to 6 numeric characters (Optional) Freight amount. Character length and limitations: 1 to 15 numeric characters (Optional)Handling amount. Character length and limitations: 1 to 15 numeric characters (Optional) Tracking number. Character length and limitations: 1 to 30 alphanumeric characters (Optional) Drop-off address1. Character length and limitations: 1 to 40 alphanumeric characters (Optional) Drop-off city. Character length and limitations: 2 to 30 alphanumeric characters (Optional) Drop-off state. Character length and limitations: 2 alphanumeric characters (Optional) Drop-off postal or zip code. Character length and limitations: 3 to 15 alphanumeric characters (Optional) Drop-off country. Character length and limitations: 2 to 3 alphanumeric characters (Optional) UNSPSC code. Character length and limitations: 1 to 30 alphanumeric characters

Example American Express Level 3 Transaction Parameter String

TRXTYPE=S&TENDER=C&partner=partner&PWD=test&USER=test&ACCT=378734493671000& EXPDATE=1213&AMT=5.00&COMMENT1=PCARD Test&COMMENT2=Testing&BILLTOZIP=940151 234&BILLTOSTREET=123 Lincoln WAY&CVV2=0123&SHIPTOCOUNTRY=USA&CUSTCODE=12345 &FREIGHTAMT=1.00&ORDERDATE=021700&HANDLINGAMT=1.00&PONUM=123456789012345678 9012345&SHIPFROMZIP=940151234&SHIPTOZIP=940151234&TAXAMT=1.00&TAXEXEMPT=N&L _UPC1=PN&L_QTY1=1&L_DESC1=Test123&L_UOM1=12&L_COST1=1.00&L_PRODCODE1=123&L_ COSTCENTERNUM1=55&L_TAXAMT1=0&L_QTY2=1&L_UPC1=PN&L_DESC2=Test&L_UOM2=12&L_C OST2=1.00&L_PRODCODE2=1234&L_COSTCENTERNUM2=55&L_TAXAMT2=1.00&REQNAME=Rober t&SHIPTOZIP=543210&INVNUM=123456789&VERBOSITY=HIGH

Gateway Developer Guide and Reference

19 July 2013

161

Submitting Purchasing Card Level 2 and 3 Transactions

Elavon (Formerly Nova) Purchasing Card Transaction Processing

Elavon (Formerly Nova) Purchasing Card Transaction Processing

Elavon supports Level 2 for Visa and MasterCard sale, credit, and delayed capture transactions.

Elavon Level 2 Parameters

To get the discount rate, include both Level 2 parameters listed in the following table. Pass these parameters in authorization and sale transactions.
Level 2 Parameters CUSTCODE Description (Required) Customer code. Character length and limitations: 1 to 16 alphanumeric characters (Required) Sales tax. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). To qualify for Level 2 discounts, this value must not be all zeros or blank spaces. Character length and limitations: numeric

TAXAMT

Elavon Additional Parameters

The following parameters are recommended to obtain the best rates for purchasing card transactions with Elavon:
Field COMMCARD Description (Optional) Type of purchasing card account number sent. Is one of the following values: P = Purchase Card C = Corporate Card B = Business Card U = Unknown (default) N = None Character length and limitations: 1 alphanumeric character, defaults to U PONUM (Optional) Purchase order number. Character length and limitations: 25 alphanumeric characters, when used provides best rate (Optional)Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: 10 currency characters, when used provides best rate

TAXAMT

162

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

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

Example Elavon Level 2 Transaction Parameter String

TRXTYPE=S&ACCT=5105105105105100&AMT=20.10&BILLTOCITY=Mountain View&COMMENT1 =L2 Testing&EXPDATE=1215&BILLTOFIRSTNAME=Cardholder First Name&BILLTOLASTNA ME=Cardholder Last Name&PARTNER=PayPal&PWD=pwd&BILLTOSTATE=CA&BILLTOSTREET= 123 Main St.&TENDER=C&USER=user&BILLTOZIP=94043&CUSTCODE=123456&TAXAMT=1.34

First Data Merchant Services (FDMS) Nashville Purchasing Card Transaction Processing
NOT E :

FDMS Nashville supports Level 2 transaction processing only.

The following parameters are recommended to obtain the best rates for purchasing card transactions with FDMS Nashville.

FDMS Nashville Commercial Card Parameters

Field COMMCARD Description (Optional) Type of purchasing card account number sent. Is one of the following values: P = Purchase Card C = Corporate Card B = Business Card U = Unknown (default) N = None Character length and limitations: 1 alphanumeric character, defaults to U DUTYAMT (Optional) Sometimes called import tax. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: 10 currency characters (Optional) Freight amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: 10 currency characters (Optional) Purchase order number. Character length and limitations: 25 alphanumeric characters, provides best rate when used (Optional)Ship to postal code (called zip code in the USA). Character length and limitations: 9 numeric characters, provides best rate when used

FREIGHTAMT

PONUM

SHIPTOZIP

Gateway Developer Guide and Reference

19 July 2013

163

Submitting Purchasing Card Level 2 and 3 Transactions

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

Field TAXAMT

Description (Optional)Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: 10 currency characters, provides best rate when used (Optional) Is the customer tax exempt? Character length and limitations: 1 alphanumeric character, Y or N

TAXEXEMPT

First Data Merchant Services (FDMS) North Purchasing Card Transaction Processing
The following parameters are recommended to obtain the best rates for Level 2 and Level 3 purchasing card transactions with FDMS North.

FDMS North Purchasing Parameters

Field SHIPTOCOUNTRY Description (Optional) Destination country code. Visa and MasterCard are different. Character length and limitations: 3 alpha characters (Optional) Discount amount on total sale Character length and limitations: 10 currency characters (Optional) Sometimes called import tax. If the currency uses a decimal, then the value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: 10 currency characters Character length and limitations: 10 currency characters (Optional) Purchase order number / merchant-related data. Character length and limitations: 25 alphanumeric characters, provides best rate when used (Optional) The postal code (called zip code in the USA) from which shipping occurs. Character length and limitations: 9 numeric characters, provides best rate when used (Optional) Ship to postal code (called zip code in the USA). Character length and limitations: 9 numeric characters, provides best rate when used (Optional) Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: 10 currency characters

DISCOUNT

DUTYAMT

FREIGHTAMT PONUM

SHIPFROMZIP

SHIPTOZIP

TAXAMT

164

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

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

FDMS North Purchasing Card Line Item Parameters

Line item data (Level 3) describes the details of the item purchased and can be passed for each transaction. The convention for passing line item data in name-value pairs is that each namevalue starts with L_ and ends with n where n is the line item number. For example L_QTY0=1 is the quantity for line item 0 and is equal to 1, with n starting at 0. In addition, the SHIPFROMZIP parameter is required for Level 3 transactions.
FDMS North Line Item Parameters Field L_QTYn L_COMMCODEn L_DESCn L_UOMn L_COSTn L_UPCn L_DISCOUNTn L_AMTn Description (Required) Quantity (whole units only). Character length and limitations: 10 numeric characters (Optional) Item commodity code. Character length and limitations: 12alphanumeric characters (Optional) Item description. Character length and limitations: 35 alphanumeric characters (Optional) Item unit of measure. Character length and limitations: 3 alpha characters (Optional) Cost per item, excluding tax. Character length and limitations: 10 currency characters (Optional) Supplier specific product code. Character length and limitations: 12 alphanumeric characters (Optional) Discount per line item. Character length and limitations: 10 currency characters (Optional) Total line item amount including tax and discount. + for debit, - for credits. Character length and limitations: 10 currency characters (Optional) Line item tax amount. Character length and limitations: 10 currency characters

L_TAXAMTn

First Data Merchant Services South (FDMS) Purchasing Card Transaction Processing
The following parameters are recommended to obtain the best rates for Level 2 and Level 3 purchasing card transactions with FDMS South.

Gateway Developer Guide and Reference

19 July 2013

165

Submitting Purchasing Card Level 2 and 3 Transactions

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

FDMS South Level 2 and Level 3 Purchasing Card Parameters

Field BILLTOCITY Description (Optional) Cardholders city. Character length and limitations: 13 alpha characters (Optional) Destination Country Code. Visa and MasterCard are different. Refer to Country Code tables. Character length and limitations: 3 alpha characters (Optional) Customer code/customer reference ID. Character length and limitations: 17 alphanumeric characters Discount amount on total sale. Character length and limitations: 10 currency characters (Optional) Sometimes called import tax. If the currency uses a decimal, then the value must include a decimal and the exact amount to the cent(42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: 10 currency characters (Optional) Cardholders first name. Character length and limitations: 15 alpha characters (Optional) Freight amount. If the currency uses a decimal, then the value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: 10 currency characters (Optional) Merchant invoice number. This reference number (PNREFgenerated by PayPal) is used for authorizations and settlements. The acquirer decides if this information will appear on the merchants bank reconciliation statement. Character length and limitations: 9 alphanumeric characters (Optional) Cardholders last name. Character length and limitations: 15 alpha characters (Optional) Order date. Format is mmddyy with no slashes or dashes. For example, July 28, 2003 is 072803. Character length and limitations: 6 numeric characters

SHIPTOCOUNTRY

CUSTCODE

DISCOUNT

DUTYAMT

BILLTOFIRSTNAME

FREIGHTAMT

INVNUM

BILLTOLASTNAME

ORDERDATE

166

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

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

Field ORDERTIME

Description (Optional) Order time and date. Format is either YYYY-MM-DD or YYYY-MM-DD HH:MI:SS (where HH is in 24-hour time). If the value does not conform to one of the formats or if the date is not valid (for example, 2004-17-35), then the transaction is rejected with a RESULT=7 (SIG_FIELD_ERR) and 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. Character length and limitations: 19 alphanumeric characters (Optional) Purchase order number / merchant-related data. Character length and limitations: 25 alphanumeric characters, provides best rate when used (Optional) The postal code (called zip code in the USA) from which shipping occurs. Character length and limitations: 9 numeric characters, provides best rate when used (Optional) Ship to postal code (called zip code in the USA). Character length and limitations: 9 numeric characters, provides best rate when used (Optional) Cardholders state. Character length and limitations: 2 alpha characters (Optional) Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: 10 currency characters, provides best rate when used (Optional) Is the customer tax exempt? Character length and limitations: 1 alphanumeric character, Y or N

PONUM

SHIPFROMZIP

SHIPTOZIP

BILLTOSTATE

TAXAMT

TAXEXEMPT

FDMS South Line Item Parameters

Line item data (Level 3) describes the details of the item purchased and can be can be passed for each transaction. The convention for passing line item data in name-value pairs is that each name-value starts with L_ and ends with n where n is the line item number. For example L_QTY0=1 is the quantity for line item 0 and is equal to 1, with n starting at 0.
FDMS South Purchasing Card Line Item Parameters Field L_QTYn L_COMMCODEn Description (Required) Quantity (whole units only). Character length and limitations: 10 numeric characters (Optional) Item commodity code. Character length and limitations: 12 alphanumeric characters

Gateway Developer Guide and Reference

19 July 2013

167

Submitting Purchasing Card Level 2 and 3 Transactions

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

Field L_DESCn L_UOMn L_COSTn L_PRODCODEn L_DISCOUNTn L_AMTn

Description (Optional) Item description. Character length and limitations: 35 alphanumeric characters (Optional) Item unit of measure. Character length and limitations: 3 alpha characters (Optional) Cost per item, excluding tax. Character length and limitations: 10 currency characters (Optional) Supplier-specific product code. Character length and limitations: 12 alphanumeric characters (Optional) Discount per line item. Character length and limitations: 10 currency characters (Required) Total line item amount including tax and discount. + for debit, - for credits. Character length and limitations: 10 currency characters (Optional) Line item tax amount. Character length and limitations: 10 currency characters

L_TAXAMTn

Example FDMS South Purchasing Card Level 2 and 3 Parameter String

TRXTYPE=S&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant&P WD=x1y2z3&BILLTOSTATE=CA&BILLTOFIRSTNAME=John&BILLTOLASTNAME=Smith&BILLTOCI TY=Redwood&SHIPTOCOUNTRY=USA&CUSTCODE=12345&DISCOUNT=.25&DUTYAMT=34.00&FREI GHTAMT=12.00&INVNUM=123456789&ORDERDATE=021700&PONUM=1234567890123456789012 345&SHIPFROMZIP=940151234&SHIPTOZIP=94065&TAXAMT=1.00&TAXEXEMPT=Y

Example FDMS South Line Item Parameter String

TRXTYPE=S&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant&P WD=x1y2z3&BILLTOSTATE=CA&BILLTOFIRSTNAME=John&BILLTOLASTNAME=Smith&BILLTOCI TY=Redwood&SHIPTOCOUNTRY=USA&CUSTCODE=12345&DISCOUNT=.25&DUTYAMT=34.00&FREI GHTAMT=12.00&INVNUM=123456789&ORDERDATE=021700&PONUM=1234567890123456789012 345&SHIPFROMZIP=940151234&SHIPTOZIP=94065&TAXAMT=1.00&TAXEXEMPT=Y&L_QTY1=1& L_UPC1=PN&L_DESC1=Test&L_UOM1=INQ&L_COST1=1.00&L_PRODCODE1=12345&L_DISCOUNT 1=.25&&L_AMT1=.75&L_TAXAMT1=0

168

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

Global Payments - Central Purchasing Card Transaction Processing

Global Payments - Central Purchasing Card Transaction Processing

Global Payments - Central (MAPP) supports Level 2 parameters for MasterCard, and Visa sale, credit, and delayed capture transactions.

Global Payments - Central Level 2 Parameters

Pass the following Level 2 parameters to get the discount rate.
Global Payments - Central Level 2 parameters Level 2 Parameters CUSTCODE Description (Required) Customer code. Character length and limitations: 1 to 16 alphanumeric characters (Required) Sales tax. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). To qualify for Level 2 discounts, this value must not be all zeros or blank spaces. Character length and limitations: numeric Example Global Payments - Central Level 2 Visa or MasterCard Transaction Parameter String TRXTYPE=S&ACCT=5105105105105100&AMT=20.10&BILLTOCITY=Mountain View&COMMENT1 =L2 Testing&EXPDATE=1209&BILLTOFIRSTNAME=Cardholder First Name&BILLTOLASTNA ME=Cardholder Last Name&PARTNER=PayPal&PWD=pwd&BILLTOSTATE=CA&BILLTOSTREET= 123 Main St.&TENDER=C&USER=user&BILLTOZIP=94043&CUSTCODE=123456&TAXAMT=1.34

TAXAMT

Global Payments - East Purchasing Card Transaction Processing

Global Payments - East supports Level 2 parameters for American Express, MasterCard, and Visa.

Global Payments - East Level 2 Parameters

Pass the following Level 2 parameters in authorization and sale transactions to get the discount rate.

Gateway Developer Guide and Reference

19 July 2013

169

Submitting Purchasing Card Level 2 and 3 Transactions

Heartland Purchasing Card Transaction Processing

Level 2 Parameters CUSTCODE

Description (Required) Customer code. Character length and limitations: 1 to 16 alphanumeric characters (Required) Sales tax. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). To qualify for Level 2 discounts, this value must not be all zeros or blank spaces. Character length and limitations: numeric

TAXAMT

Example Global Payments - East Level 2 Visa or MasterCard Transaction Parameter String
TRXTYPE=S&ACCT=5105105105105100&AMT=20.10&BILLTOCITY=Mountain View&COMMENT1 =L2 Testing&EXPDATE=1215&BILLTOFIRSTNAME=Cardholder FirstName&BILLTOLASTNAM E=Cardholder LastName&PARTNER=PayPal&PWD=pwd&BILLTOSTATE=CA&BILLTOSTREET=12 3 Main St.&TENDER=C&USER=user&BILLTOZIP=94043&CUSTCODE=123456&TAXAMT=1.34

Global Payments - Central (MAPP) supports Level 2 for MasterCard, and Visa Sale, Credit, and Delayed Capture transactions.

Heartland Purchasing Card Transaction Processing

Heartland Level 2 Parameters

Heartland supports MasterCard and Visa for Level 2 processing. Heartland indicates in the authorization response whether the credit card in the transaction is a commercial card. Based on the commercial card indicator, Payflow will format the Level 2 information in the settlement request.
Heartland Level 2 Transaction Data

To get the discount rate, pass the Level 2 values marked Required in the following table.
Parameter PONUM Description (Required) Customer reference ID. Character length and limitations: 1 to 16 alphanumeric characters

170

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

Heartland Purchasing Card Transaction Processing

Parameter TAXAMT

Description (Required) Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). To qualify for Level 2 discounts, this value must not be all zeros or blank spaces. Character length and limitations: numeric (Optional) Tax amount identifier. Character length and limitations: 1 alpha character, Y or N

TAXEXEMPT

Example Heartland Level 2 Visa Transaction Parameter String TRXTYPE=S&ACCT=4111111111111111&AMT=20.02&BILLTOCITY=Mountain View&COMMENT1 =L2 Testing&EXPDATE=1215&INVNUM=661254585&BILLTOFIRSTNAME=CardHolder Name&P ARTNER=PayPal&PWD=pwd&BILLTOSTATE=CA&BILLTOSTREET=123 Main St.&TAXAMT=1.01& TAXEXEMPT=N&TENDER=C&USER=user&BILLTOZIP=94043

Heartland Level 3 MasterCard Parameters

To qualify for Level 3, the authorization response for the transaction must have the commercial card indicator set and one or more line items should be present in the delayed capture or sale request. Level 2 transaction parameters marked as Required are required for Level 3 transactions. Level 3 transactions that do not include the required Level 2 values are rejected.
IM PORT AN T :

The values required for Level 3 status vary by bank, so contact your bank for details.

Heartland Level 2 MasterCard Parameters Required for Level 3 Transactions Parameter PONUM Description (Required) Purchase identifier. Character length and limitations: 25 alphanumeric characters (Required) Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). To qualify for Level 2 discounts, this value must not be all zeros or blank spaces. Character length and limitations: numeric (Optional) Local tax. Character length and limitations: 12 numeric characters (Optional) Local tax incl flag. Character length and limitations: 1 alphanumeric, Y or N

TAXAMT

LOCALTAXAMT

TAXEXEMPT

Gateway Developer Guide and Reference

19 July 2013

171

Submitting Purchasing Card Level 2 and 3 Transactions

Heartland Purchasing Card Transaction Processing

Parameter NATIONALTAXAMT

Description (Optional) National tax amount. You may omit this parameter if there is no such tax. Character length and limitations: 12 numeric characters (Required) Purchase Order number or customer reference ID. The PNREF value is sent if no value is provided. Character length and limitations: 9 alphanumeric characters Heartland Level 3 MasterCard Extended Data

INVNUM

The parameters listed in the table below apply to Level 3 MasterCard transactions as extended data.
Parameter FREIGHTAMT Description (Optional) Freight amount. Character length and limitations: 12 numeric characters (Optional) Duty amount. Character length and limitations: 12 numeric characters (Required) The zip code of the address to which the goods are shipped. Character length and limitations: 10 alphanumeric characters (Required) The postal code (called zip code in the USA) from which shipping occurs. Character length and limitations: 10 alphanumeric characters (Optional) Destination country code. Character length and limitations: 3 alphanumeric characters (Optional) Alternate tax amount. Character length and limitations: 9 numeric characters

DUTYAMT

SHIPTOZIP

SHIPFROMZIP

SHIPTOCOUNTRY

ALTTAXAMT

Heartland Level 3 MasterCard Line Item Detail Records

NOT E :

For these values, n is a sequence counter that should begin with 1 and increase in sequence. Each line item should also contain quantity (L_QTYn) and unit price (L_COSTn) fields.
Description (Optional) Item commodity code. Character length and limitations: 12 alphanumeric characters (Required) Item descriptor. Character length and limitations: 35 alphanumeric characters (Optional) Product code. Character length and limitations: 12 alphanumeric characters

Parameter L_COMMCODEn L_DESCn L_UPCn

172

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

Heartland Purchasing Card Transaction Processing

Parameter L_QTYn L_UOMn L_COSTn L_TAXAMTn L_TAXRATEn L_DISCOUNTn L_AMTn

Description (Required) Quantity. Character length and limitations: 12 numeric characters (Required) Unit of measure code. Character length and limitations: 12 alphanumeric characters (Required) Unit cost. Character length and limitations: 12 numeric characters (Optional) VAT/tax amount. Character length and limitations: 12 numeric characters (Optional) VAT/tax rate. Character length and limitations: 4 numeric characters (Optional) Discount per line item. Character length and limitations: 12 numeric characters (Optional) Line-item total. Character length and limitations: 12 numeric characters

Example Heartland Level 3 MasterCard Transaction Parameter String.

TRXTYPE=S&TENDER=C&PARTNER=Partner&USER=User&PWD=Password&ACCT=552500000000 0005&EXPDATE=1215&AMT=1.00&BILLTOSTREET=5199 JOHNSON&BILLTOZIP=94588&ALTTAX AMT=1.00&CUSTVATREGNUM=11111&LOCALTAXAMT=1.00&NATIONALTAXAMT=1.00&COMMCODE= 22222&VATAXAMT=1.00&VATAXPERCENT=10&TAXEXEMPT=Y&DISCOUNT=1.00&FREIGHTAMT=1. 00&DUTYAMT=1.00&SHIPTOZIP=33333&SHIPFROMZIP=44444&SHIPTOCOUNTRY=840&ORDERDA TE=020725&L_COMMCODE1=123456789ABC&L_DESC1=Line item 1 description&L_UPC1=C BA987654321&L_QTY1=1&L_UOM1=123456789012&L_COST1=1.00&L_TAXAMT1=1.00&L_TAXR ATE1=1.00&L_DISCOUNT1=1.00&L_AMT1=1.00&L_TAXTYPE1=TT3

Heartland Level 3 Visa Parameters

To qualify for Level 3 transactions, the authorization response for the transaction must have the commercial card indicator set and one or more line items should be present in the delayed capture or sale request. Level 2 transaction parameters marked as Required are required for Level 3 transactions. Level 3 transactions that do not include the required Level 2 values are rejected.
IM PORT AN T :

The values required for Level 3 status vary by bank, so contact your bank for details.

Heartland Level 2 Visa Parameters Required for Level 3 Transactions Parameter PONUM Description (Required) Purchase identifier. TheTransaction ID is sent if no value is provided. Character length and limitations: 25 alphanumeric characters

Gateway Developer Guide and Reference

19 July 2013

173

Submitting Purchasing Card Level 2 and 3 Transactions

Heartland Purchasing Card Transaction Processing

Parameter TAXAMT

Description (Required) Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: numeric (Optional) Local tax amount. Character length and limitations: 12 numeric characters (Optional) Local tax incl flag. Character length and limitations: 1 alphanumeric, Y or N (Optional) National tax amount. Character length and limitations: 12 numeric characters (Required) Purchase order number/customer reference ID. The Transaction ID is sent if no value is provided. Character length and limitations: 9 alphanumeric characters Heartland Level 3 Visa Extended Data

LOCALTAXAMT

TAXEXEMPT

NATIONALTAXAMT

INVNUM

The parameters listed in the table below apply to Level 3 MasterCard transactions as extended data.
Parameter COMMCODE Description (Optional) Summary commodity code identifier for the business. Character length and limitations: 4 alphanumeric characters (Optional) Discount amount. Character length and limitations: 12 numeric characters (Optional) Freight amount. Character length and limitations: 12 numeric characters (Optional)Duty amount. Character length and limitations: 12 numeric characters (Required) Order date. Format is mmddyy with no slashes or dashes. For example, July 28, 2003 is 072803. Character length and limitations: 6 numeric characters (Required) The zip code of the address to which the goods are shipped. Character length and limitations: 10 alphanumeric characters (Required) The postal code (called zip code in the USA) from which shipping occurs. Character length and limitations: 10 alphanumeric characters (Optional) Destination country code. Character length and limitations: 3 alphanumeric characters

DISCOUNT

FREIGHTAMT

DUTYAMT

ORDERDATE

SHIPTOZIP

SHIPFROMZIP

SHIPTOCOUNTRY

174

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

Heartland Purchasing Card Transaction Processing

Parameter VATREGNUM

Description (Required) VAT registration number. Can be part of the registration data or passed with each transaction. Character length and limitations: 20 alphanumeric characters (Required) Unique VAT inventory reference number. Can be part of the registration data or passed with each transaction. Character length and limitations: 9 alphanumeric characters (Required) Customer VAT registration number. Character length and limitations: 13 alphanumeric characters (Optional) VAT/tax amount (freight/shipping). Character length and limitations: 12 numeric characters (Optional) VAT/tax rate (freight/shipping). Character length and limitations: 4 numeric characters

FREIGHTAMT

CUSTVATREGNUM

VATTAXAMT

VATTAXPERCENT

Heartland Level 3 Visa Line Item Detail Records Parameter L_COMMCODEn L_DESCn L_UPCn L_QTYn L_UOMn L_COSTn L_TAXAMTn L_TAXRATEn L_DISCOUNTn L_AMTn Description (Optional) Item commodity code. Character length and limitations: 12 alphanumeric characters (Required) Item descriptor. Character length and limitations: 35 alphanumeric characters (Optional) Product code. Character length and limitations: 12 alphanumeric characters (Required) Quantity. Character length and limitations: 12 numeric characters (Required) Unit of measure code. Character length and limitations: 12 alphanumeric characters (Required) Unit cost. Character length and limitations: 12 numeric characters (Optional) VAT/tax amount. Character length and limitations: 12 numeric characters (Optional) VAT/tax rate. Character length and limitations: 4 numeric characters (Optional) Discount per line item. Character length and limitations: 12 numeric characters (Optional) Line-item total. Character length and limitations: 12 numeric characters

Gateway Developer Guide and Reference

19 July 2013

175

Submitting Purchasing Card Level 2 and 3 Transactions

Litle Purchasing Card Transaction Processing

Example Heartland Level 3 Visa Transaction Parameter String TRXTYPE=S&TENDER=C&PARTNER=Partner&USER=User&PWD=Password&ACCT=411111111111 1111&EXPDATE=1215&AMT=1.00&BILLTOSTREET=5199 JOHNSON&TAXAMT=1.06&BILLTOZIP= 94588&ALTTAXAMT=1.00&CUSTVATREGNUM=11111&LOCALTAXAMT=1.01&NATIONALTAXAMT=1. 02&COMMCODE=22222&VATAXAMT=1.03&VATAXPERCENT=55&TAXEXEMPT=N&DISCOUNT=.50&FR EIGHTAMT=1.00&DUTYAMT=1.00&SHIPTOZIP=33333&SHIPFROMZIP=44444&SHIPTOCOUNTRY= 840&ORDERDATE=020725&L_COMMCODE1=123456789ABC&L_DESC1=Line item 1 descripti on&L_UPC1=CBA987654321&L_QTY1=1&L_UOM1=123456789012&L_COST1=1.50&L_TAXAMT1= 1.05&L_TAXRATE1=12&L_DISCOUNT1=.50&L_AMT1=1.00&L_TAXTYPE1=TT1

Litle Purchasing Card Transaction Processing

Litle Level 2 Parameters

The Litle platform supports Level 2 transaction data.
Litle Level 2 Parameters Field CUSTREF Description (Optional) Reference, such as a purchase order number, used by the customer for the purchase. Character length and limitations: 17 alphanumeric characters (Optional) Discount amount for the order. Character length and limitations: The decimal is implied. If, for example, you specify 500, this value is equivalent to $5.00. 8 numeric characters (Optional) Duty amount on the total purchased for the order. Character length and limitations: The decimal is implied. If, for example, you specify 500, this value is equivalent to $5.00. 8 numeric characters (Optional) Shipping amount for the order. Character length and limitations: The decimal is implied. If, for example, you specify 500, this value is equivalent to $5.00. 8 numeric characters (Optional) Tax amount included in the amount of the transaction. Character length and limitations: The decimal is implied. If, for example, you specify 500, this value is equivalent to $5.00. 8 numeric characters (Optional) Amount of this line-item including tax, where n is a line-item number from 1 to 99. L_AMTn - L_TAXAMTn = line-item total. Character length and limitations: The decimal is implied. If, for example, you specify 500, this value is equivalent to $5.00. 8 numeric characters

DISCOUNT

DUTYAMT

FREIGHTAMT

TAXAMT

L_AMTn

176

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

Litle Purchasing Card Transaction Processing

Field L_COMMCODEn

Description (Optional) Identifier assigned by the card acceptor that categorizes the purchased item, where n is a line-item number from 1 to 99. Character length and limitations: 12 alphanumeric characters (Required if L_QTYn is supplied) Price of one unit of the item purchased, where n is a line-item number from 1 to 99. Character length and limitations: 12 numeric characters (Required) Description of this line-item, where n is a line-item number from 1 to 99. Character length and limitations: 26 alphanumeric characters (Optional) Discount per line item, where n is a line-item number from 1 to 99. Character length and limitations: The decimal is implied. If, for example, you specify 500, this value is equivalent to $5.00. 8 numeric characters (Optional) Supplier-specific product code of the purchased item, where n is a lineitem number from 1 to 99. Character length and limitations: 12 numeric characters (Optional) Number of items purchased, where n is a line-item number from 1 to 99. Character length and limitations: 12 numeric characters (Optional) Line item tax amount, where n is a line-item number from 1 to 99. L_AMTn - L_TAXAMTn = line-item total. Characteristic length and limitations: The decimal is implied. If, for example, you specify 500, this value is equivalent to $5.00. 8 numeric characters (Optional) Unit of measure of the purchased item (such as kit, pair, gallon or month), where n is a line-item number from 1 to 99. Character length and limitations: 12 alphanumeric characters

L_COSTn

L_DESCn L_DISCOUNTn

L_PRODCODEn

L_QTYn L_TAXAMTn

L_UOMn

Litle Level 3 Parameters

The Litle platform supports Level 3 transaction data.
Litle Level 3 Parameters Field CUSTREF Description (Optional) Reference, such as a purchase order number, used by the customer for the purchase. Character length and limitations: 17 alphanumeric characters (Optional) Discount amount for the order. Character length and limitations: The decimal is implied. If, for example, you specify 500, this value is equivalent to $5.00. 8 numeric characters (Optional) Duty amount on the total purchased for the order. Character length and limitations: The decimal is implied. If, for example, you specify 500, this value is equivalent to $5.00. 8 numeric characters

DISCOUNT

DUTYAMT

Gateway Developer Guide and Reference

19 July 2013

177

Submitting Purchasing Card Level 2 and 3 Transactions

Litle Purchasing Card Transaction Processing

Field FREIGHTAMT

Description (Optional) Shipping amount for the order. Character length and limitations: The decimal is implied. If, for example, you specify 500, this value is equivalent to $5.00. 8 numeric characters (Optional) Tax amount included in the amount of the transaction. Character length and limitations: The decimal is implied. If, for example, you specify 500, this value is equivalent to $5.00. 8 numeric characters (Optional) Amount of this line-item including tax, where n is a line-item number from 1 to 99. L_AMTn - L_TAXAMTn = line-item total. Character length and limitations: The decimal is implied. If, for example, you specify 500, this value is equivalent to $5.00. 8 numeric characters (Optional) Identifier assigned by the card acceptor that categorizes the purchased item, where n is a line-item number from 1 to 99. Character length and limitations: 12 alphanumeric characters (Required if L_QTYn is supplied) Price of one unit of the item purchased, where n is a line-item number from 1 to 99. Character length and limitations: 12 numeric characters (Required) Description of this line-item, where n is a line-item number from 1 to 99. Character length and limitations: 26 alphanumeric characters (Optional) Discount per line item, where n is a line-item number from 1 to 99. Character length and limitations: The decimal is implied. If, for example, you specify 500, this value is equivalent to $5.00. 8 numeric characters (Optional) Supplier-specific product code of the purchased item, where n is a lineitem number from 1 to 99. Character length and limitations: 12 numeric characters (Optional) Number of items purchased, where n is a line-item number from 1 to 99. Character length and limitations: 12 numeric characters (Optional) Line item tax amount, where n is a line-item number from 1 to 99. L_AMTn - L_TAXAMTn = line-item total. Characteristic length and limitations: The decimal is implied. If, for example, you specify 500, this value is equivalent to $5.00. 8 numeric characters (Optional) Unit of measure of the purchased item (such as kit, pair, gallon or month), where n is a line-item number from 1 to 99. Character length and limitations: 12 alphanumeric characters

TAXAMT

L_AMTn

L_COMMCODEn

L_COSTn

L_DESCn L_DISCOUNTn

L_PRODCODEn

L_QTYn L_TAXAMTn

L_UOMn

178

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

Merchant e-Solutions Purchasing Card Transaction Processing

Merchant e-Solutions Purchasing Card Transaction Processing

Merchant e-Solutions Level 2 Parameters

Merchant e-Solutions supports MasterCard and Visa for Level 2 processing. Merchant e-Solutions indicates in the authorization response whether the credit card in the transaction is a commercial card. Based on the commercial card indicator, Payflow will format the Level 2 information in the settlement request.
Merchant e-Solutions Level 2 Transaction Data

To get the discount rate, Level 2 values marked as Required in the following table must be present.
Parameter PONUM Description (Required) Customer reference ID. Character length and limitations: 1 to 16 alphanumeric characters (Required) Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). To qualify for Level 2 discounts, this value must not be all zeros or blank spaces. Character length and limitations: numeric (Optional) Tax amount identifier. Character length and limitations: 1 alpha character, Y or N

TAXAMT

TAXEXEMPT

Example Merchant e-Solutions Level 2 Visa Transaction Parameter String TRXTYPE=S&ACCT=4111111111111111&AMT=20.02&BILLTOCITY=Mountain View&COMMENT1 =L2 Testing&EXPDATE=1215&INVNUM=661254585&BILLTOFIRSTNAME=CardHolder Name&P ARTNER=PayPal&PWD=pwd&BILLTOSTATE=CA&BILLTOSTREET=123 Main St.&TAXAMT=1.01& TAXEXEMPT=N&TENDER=C&USER=user&BILLTOZIP=94043

Merchant e-Solutions Level 3 MasterCard Parameters

To qualify for Level 3, the authorization response for the transaction must have the commercial card indicator set and one or more line items should be present in the delayed capture or sale request. Level 2 transaction parameters marked as Required are required for Level 3 transactions. Level 3 transactions that do not include the required Level 2 values are rejected.

Gateway Developer Guide and Reference

19 July 2013

179

Submitting Purchasing Card Level 2 and 3 Transactions

Merchant e-Solutions Purchasing Card Transaction Processing
IM PORT AN T :

The values required for Level 3 status vary by bank, so contact your bank for details.

Merchant e-Solutions Level 2 MasterCard Parameters Required for Level 3 Transactions Parameter PONUM Description (Required) Purchase identifier. Character length and limitations: 25 alphanumeric characters (Required) Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). To qualify for Level 2 discounts, this value must not be all zeros or blank spaces. Character length and limitations: numeric (Optional) Local tax. Character length and limitations: 12 numeric characters (Optional) Local tax incl flag. Character length and limitations: 1 alphanumeric, Y or N (Optional) National tax amount. You may omit this parameter if there is no such tax. Character length and limitations: 12 numeric characters (Required) Purchase Order number or customer reference ID. The PNREF value is sent if no value is provided. Character length and limitations: 9 alphanumeric characters Merchant e-Solutions Level 3 MasterCard Extended Data

TAXAMT

LOCALTAXAMT

TAXEXEMPT

NATIONALTAXAMT

INVNUM

The parameters listed in the table below apply to Level 3 MasterCard transactions as extended data.
Parameter FREIGHTAMT Description (Optional) Freight amount. Character length and limitations: 12 numeric characters (Optional) Duty amount. Character length and limitations: 12 numeric characters (Required) The zip code of the address to which the goods are shipped. Character length and limitations: 10 alphanumeric characters (Required) The postal code (called zip code in the USA) from which shipping occurs. Character length and limitations: 10 alphanumeric characters (Optional) Destination country code. Character length and limitations: 3 alphanumeric characters

DUTYAMT

SHIPTOZIP

SHIPFROMZIP

SHIPTOCOUNTRY

180

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

Merchant e-Solutions Purchasing Card Transaction Processing

Parameter ALTTAXAMT

Description (Optional) Alternate tax amount. Character length and limitations: 9 numeric characters

Merchant e-Solutions Level 3 MasterCard Line Item Detail Records

NOT E :

For the following values, n is a sequence counter that should begin with 1 and increase in sequence. With each line item, include the quantity (L_QTYn) and unit price (L_COSTn) fields.
Description (Optional) Item commodity code. Character length and limitations: 12 alphanumeric characters (Required) Item descriptor. Character length and limitations: 35 alphanumeric characters (Optional) Product code. Character length and limitations: 12 alphanumeric characters (Required) Quantity. Character length and limitations: 12 numeric characters (Required) Unit of measure code. Character length and limitations: 12 alphanumeric characters (Required) Unit cost. Character length and limitations: 12 numeric characters (Optional) VAT/tax amount. Character length and limitations: 12 numeric characters (Optional) VAT/tax rate. Character length and limitations: 4 numeric characters (Optional) Discount per line item. Character length and limitations: 12 numeric characters (Optional) Line-item total. Character length and limitations: 12 numeric characters

Parameter L_COMMCODEn L_DESCn L_UPCn L_QTYn L_UOMn L_COSTn L_TAXAMTn L_TAXRATEn L_DISCOUNTn L_AMTn

Example Merchant e-Solutions Level 3 MasterCard Transaction Parameter String.

TRXTYPE=S&TENDER=C&PARTNER=Partner&USER=User&PWD=Password&ACCT=552500000000 0005&EXPDATE=1215&AMT=1.00&BILLTOSTREET=5199 JOHNSON&BILLTOZIP=94588&ALTTAX AMT=1.00&CUSTVATREGNUM=11111&LOCALTAXAMT=1.00&NATIONALTAXAMT=1.00&COMMCODE= 22222&VATAXAMT=1.00&VATAXPERCENT=10&TAXEXEMPT=Y&DISCOUNT=1.00&FREIGHTAMT=1. 00&DUTYAMT=1.00&SHIPTOZIP=33333&SHIPFROMZIP=44444&SHIPTOCOUNTRY=840&ORDERDA TE=020725&L_COMMCODE1=123456789ABC&L_DESC1=Line item 1 description&L_UPC1=C BA987654321&L_QTY1=1&L_UOM1=123456789012&L_COST1=1.00&L_TAXAMT1=1.00&L_TAXR ATE1=1.00&L_DISCOUNT1=1.00&L_AMT1=1.00&L_TAXTYPE1=TT3

Gateway Developer Guide and Reference

19 July 2013

181

Submitting Purchasing Card Level 2 and 3 Transactions

Merchant e-Solutions Purchasing Card Transaction Processing

Merchant e-Solutions Level 3 Visa Parameters

To qualify for Level 3 transactions, the authorization response for the transaction must have the commercial card indicator set and one or more line items should be present in the delayed capture or sale request. Level 2 transaction parameters marked as Required are required for Level 3 transactions. Level 3 transactions that do not include the required Level 2 values are rejected.
IM PORT AN T :

The values required for Level 3 status vary by bank, so contact your bank for details.

Merchant e-Solutions Level 2 Visa Parameters Required for Level 3 Transactions Parameter PONUM Description (Required) Purchase identifier. TheTransaction ID is sent if no value is provided. Character length and limitations: 25 alphanumeric characters (Required) Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: numeric (Optional) Local tax amount. Character length and limitations: 12 numeric characters (Optional) Local tax incl flag. Character length and limitations: 1 alphanumeric, Y or N (Optional) National tax amount. Character length and limitations: 12 numeric characters (Required) Purchase order number/customer reference ID. The Transaction ID is sent if no value is provided. Character length and limitations: 9 alphanumeric characters Merchant e-Solutions Level 3 Visa Extended Data

TAXAMT

LOCALTAXAMT

TAXEXEMPT

NATIONALTAXAMT

INVNUM

The parameters listed in the table below apply to Level 3 MasterCard transactions as extended data.
Parameter COMMCODE Description (Optional) Summary commodity code identifier for the business. Character length and limitations: 4 alphanumeric characters (Optional) Discount amount. Character length and limitations: 12 numeric characters

DISCOUNT

182

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

Merchant e-Solutions Purchasing Card Transaction Processing

Parameter FREIGHTAMT

Description (Optional) Freight amount. Character length and limitations: 12 numeric characters (Optional)Duty amount. Character length and limitations: 12 numeric characters (Required) Order date. Format is mmddyy with no slashes or dashes. For example, July 28, 2003 is 072803. Character length and limitations: 6 numeric characters (Required) The zip code of the address to which the goods are shipped. Character length and limitations: 10 alphanumeric characters (Required) The postal code (called zip code in the USA) from which shipping occurs. Character length and limitations: 10 alphanumeric characters (Optional) Destination country code. Character length and limitations: 3 alphanumeric characters (Required) VAT registration number. Can be part of the registration data or passed with each transaction. Character length and limitations: 20 alphanumeric characters (Required) Unique VAT inventory reference number. Can be part of the registration data or passed with each transaction. Character length and limitations: 9 alphanumeric characters (Required) Customer VAT registration number. Character length and limitations: 13 alphanumeric characters (Optional) VAT/tax amount (freight/shipping). Character length and limitations: 12 numeric characters (Optional) VAT/tax rate (freight/shipping). Character length and limitations: 4 numeric characters

DUTYAMT

ORDERDATE

SHIPTOZIP

SHIPFROMZIP

SHIPTOCOUNTRY

VATREGNUM

FREIGHTAMT

CUSTVATREGNUM

VATTAXAMT

VATTAXPERCENT

Merchant e-Solutions Level 3 Visa Line Item Detail Records Parameter L_COMMCODEn L_DESCn L_UPCn L_QTYn Description (Optional) Item commodity code. Character length and limitations: 12 alphanumeric characters (Required) Item descriptor. Character length and limitations: 35 alphanumeric characters (Optional) Product code. Character length and limitations: 12 alphanumeric characters (Required) Quantity. Character length and limitations: 12 numeric characters

Gateway Developer Guide and Reference

19 July 2013

183

Submitting Purchasing Card Level 2 and 3 Transactions

Paymentech Salem (New Hampshire) Purchasing Card Transaction Processing

Parameter L_UOMn L_COSTn L_TAXAMTn L_TAXRATEn L_DISCOUNTn L_AMTn

Description (Required) Unit of measure code. Character length and limitations: 12 alphanumeric characters (Required) Unit cost. Character length and limitations: 12 numeric characters (Optional) VAT/tax amount. Character length and limitations: 12 numeric characters (Optional) VAT/tax rate. Character length and limitations: 4 numeric characters (Optional) Discount per line item. Character length and limitations: 12 numeric characters (Optional) Line-item total. Character length and limitations: 12 numeric characters Example Merchant e-Solutions Level 3 Visa Transaction Parameter String TRXTYPE=S&TENDER=C&PARTNER=Partner&USER=User&PWD=Password&ACCT=411111111111 1111&EXPDATE=1215&AMT=1.00&BILLTOSTREET=5199 JOHNSON&TAXAMT=1.06&BILLTOZIP= 94588&ALTTAXAMT=1.00&CUSTVATREGNUM=11111&LOCALTAXAMT=1.01&NATIONALTAXAMT=1. 02&COMMCODE=22222&VATAXAMT=1.03&VATAXPERCENT=55&TAXEXEMPT=N&DISCOUNT=.50&FR EIGHTAMT=1.00&DUTYAMT=1.00&SHIPTOZIP=33333&SHIPFROMZIP=44444&SHIPTOCOUNTRY= 840&ORDERDATE=020725&L_COMMCODE1=123456789ABC&L_DESC1=Line item 1 descripti on&L_UPC1=CBA987654321&L_QTY1=1&L_UOM1=123456789012&L_COST1=1.50&L_TAXAMT1= 1.05&L_TAXRATE1=12&L_DISCOUNT1=.50&L_AMT1=1.00&L_TAXTYPE1=TT1

Paymentech Salem (New Hampshire) Purchasing Card Transaction Processing

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

The Paymentech Salem (New Hampshire) platform supports Level 2 parameters for American Express, MasterCard, Visa, and Switch/Solo Maestro. The parameters in the following tables meet card acceptance and American Express reporting and statement requirements.

184

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

Paymentech Salem (New Hampshire) Purchasing Card Transaction Processing

CPC Level 2 Transaction Advice Addendum Parameters Field PONUM Description (Required) Purchase order number. Character length and limitations: 17 alphanumeric characters (Required) Ship-to postal code (called zip code in the USA). Character length and limitations: 15 alphanumeric characters (Optional) Total tax amount. Must include a decimal and be exact to the cent (42.00, not 42) and exclude comma separators (1234.56 not 1,234.56). Character length and limitations: 12 numeric characters (Optional) Description of this line item; if not provided, DESC1 (if present) is used. Character length and limitations: 140 alphanumeric characters (Optional) Charge for this line item. Must include a decimal and be exact to the cent (42.00, not 42) and exclude comma separators (1234.56 not 1,234.56). Character length and limitations: 12 numeric characters (Optional) Quantity of this line item. Character length and limitations: 3 numeric characters (Optional) Description of this line item; if not provided, DESC2 (if present) is used. Character length and limitations: 40 alphanumeric characters (Optional) Charge for this line item. Must include a decimal and be exact to the cent (42.00, not 42) and exclude comma separators (1234.56 not 1,234.56). Character length and limitations: 12 numeric characters (Optional) Quantity of this line item Character length and limitations: 3 numeric characters (Optional) Description of this line item; if not provided, DESC3 (if present) is used Character length and limitations: 40 alphanumeric characters (Optional) Charge for this line item. Must include a decimal and be exact to the cent (42.00, not 42) and exclude comma separators (1234.56 not 1,234.56). Character length and limitations: 12 numeric characters (Optional) Quantity of this line item Character length and limitations: 3 numeric characters (Optional) Description of this line item; if not provided, DESC4 (if present) is used Character length and limitations: 30 alphanumeric characters (Optional) Charge for this line item. Must include a decimal and be exact to the cent (42.00, not 42) and exclude comma separators (1234.56 not 1,234.56). Character length and limitations: 12 numeric characters (Optional) Quantity of this line item Character length and limitations: 3 numeric characters

SHIPTOZIP

TAXAMT

L_DESC1

L_AMT1

L_QTY1

L_DESC2

L_AMT2

L_QTY2

L_DESC3

L_AMT3

L_QTY3

L_DESC4

L_AMT4

L_QTY4

Gateway Developer Guide and Reference

19 July 2013

185

Submitting Purchasing Card Level 2 and 3 Transactions

Paymentech Salem (New Hampshire) Purchasing Card Transaction Processing

Location Transaction Advice Addendum Parameters Field MERCHANTNAME Description (Optional) Name of merchant. Character length and limitations: 38 alphanumeric characters (Optional) Merchants 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. (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 nonnumeric 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 (Optional) Country code of the location where the transaction took place. Character length and limitations: 3 alphanumeric characters (Optional)Merchant-assigned store or location number (or name) that uniquely identifies where the transaction took place.
N O TE :

MERCHANTSTREET

MERCHANTCITY

MERCHANTCOUNTRYCODE

MERCHANTLOCATIONID

Paymentech must enable your division for soft merchant processing or your transaction will fail with response reason code 258. Contact your Paymentech Account Manager for details.

Character length and limitations: 15 alphanumeric characters

186

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

Paymentech Salem (New Hampshire) Purchasing Card Transaction Processing

Field MERCHANTID

Description (Required) American Express-assigned service establishment number used to identify and facilitate payments to merchants.
N O TE :

Paymentech must enable your division for soft merchant processing or your transaction will fail with response reason code 258. Contact your Paymentech Account Manager for details.

Character length and limitations: 15 alphanumeric characters MERCHANTCONTACTINFO (Optional) Merchants 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.
N O TE :

Paymentech must enable your division for soft merchant processing or your transaction will fail with response reason code 258. Contact your Paymentech Account Manager for details.

Character length and limitations: 40 alphanumeric characters Transaction Advice Detail Parameters Field ADDLAMTn Description (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 (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

ADDLAMTTYPEn

Paymentech Salem (New Hampshire) Level 3 Purchasing Card Parameters

Paymentech Salem (New Hampshire) supports Level 3 parameters for MasterCard and Visa. Both Level 2 transaction parameters in the following table are required for Level 3 transactions. Level 3 transactions that do not include them are rejected.
Paymentech Salem (New Hampshire) Level 2 Parameters Required for Level 3 Transactions

To get the discount rate, pass both Level 2 parameters in the following table.
Level 2 Parameters Required for Level 3 Transactions Parameter PONUM Description (Required) Customer reference number. Character length and limitations: 1 to 17 alphanumeric characters

Gateway Developer Guide and Reference

19 July 2013

187

Submitting Purchasing Card Level 2 and 3 Transactions

Paymentech Salem (New Hampshire) Purchasing Card Transaction Processing

Parameter TAXAMT

Description (Required) Sales tax. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). To qualify for Level 2 discounts, this value must not be all zeros or blank spaces. Character length and limitations: numeric Paymentech Salem (New Hampshire) Level 3 MasterCard Parameters

Level 3 MasterCard Order Parameters Parameter FREIGHTAMT Description (Required) Freight amount. Character length and limitations: numeric (Required) Duty amount. Character length and limitations: numeric (Required) Destination zip code. (Optional) Destination country. (Required) Ship from zip code. (Required) Discount amount. Character length and limitations: numeric (Optional) Alternate tax ID. (Optional) Alternate tax amount. Character length and limitations: numeric

DUTYAMT

SHIPTOZIP SHIPTOCOUNTRY SHIPFROMZIP DISCOUNT

ALTERNATETAXID ALTERNATETAXAMT

. Level 3 MasterCard Line Item Record #1 Parameters

Parameter L_DESCn L_PRODCODEn L_QTYn L_UOMn TAXAMTn L_TAXRATEn Description (Required) Description. (Optional) Product code. (Required) Quantity. Character length and limitations: numeric characters (Required) Unit of measure. (Optional) Tax amount. Character length and limitations: numeric (Optional) Tax rate. Character length and limitations: 4 numeric characters

188

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

Paymentech Salem (New Hampshire) Purchasing Card Transaction Processing

. Level 3 MasterCard Line Item Record #2 Parameters

Parameter L_AMTn L_DISCOUNTn L_TAXTYPEn Description (Optional) Line-item total. Character length and limitations: numeric (Optional) Discount amount. Character length and limitations: numeric (Optional) Tax type applied.

Paymentech Salem (New Hampshire) Level 3 Visa Parameters Level 3 Visa Order Parameters Parameter FREIGHTAMT Description (Required) Freight amount. Character length and limitations: numeric (Required) Duty amount. Character length and limitations: numeric (Required) Destination zip code. (Optional) Destination country. (Required) Ship from zip code. (Required) Discount amount. Character length and limitations: numeric (Optional) VAT/Tax ID. Character length and limitations: numeric (Optional) VAT/Tax amount.

DUTYAMT

SHIPTOZIP SHIPTOCOUNTRY SHIPFROMZIP DISCOUNT

TAXAMT

TAXPERCENTAGE

. Level 3 Visa Line Item Record #1 Parameters

Parameter L_DESCn L_PRODCODEn L_QTYn L_UOMn TAXAMTn L_TAXRATEn Description (Required) Description. (Required) Product code. (Required) Quantity. Character length and limitations: numeric characters (Required) Unit of measure. (Optional) Tax amount. Character length and limitations: numeric (Optional) Tax rate. Character length and limitations: 4 numeric characters

Gateway Developer Guide and Reference

19 July 2013

189

Submitting Purchasing Card Level 2 and 3 Transactions

Paymentech Tampa Level 2 Purchasing Card Transaction Processing

. Level 3 Visa Line Item Record #2 Parameters

Parameter L_AMTn L_DISCOUNTn L_UPCn L_COSTn Description (Optional) Line-item total. Character length and limitations: numeric (Optional) Discount amount. Character length and limitations: numeric (Optional) Item commodity code. (Optional) Unit cost. Character length and limitations: numeric Example Paymentech Salem (New Hampshire) Level 3 MasterCard Transaction Parameter String TRXTYPE=S&TENDER=C&PARTNER=Partner&PWD=Password&USER=User&ACCT=548018000000 0024&EXPDATE=1215&AMT=1.00&COMMENT1=0508&BILLTOFIRSTNAME=Robert&BILLTOSTREE T=123 Main St.&BILLTOZIP=94065&CVV2=426&PONUM=ABCDEFGHIJ&TAXAMT=1.00&FREIGH TAMT=2.00&DUTYAMT=3.00&SHIPTOZIP=94543&SHIPTOCOUNTRY=840&SHIPFROMZIP=94509& ALTERNATETAXID=10&ALTERNATETAXAMT=4.00&L_DESC1=MC Pcard&L_UPC1=1&L_QTY1=2&L _UOM1=3&L_TAXAMT1=4&L_TAXRATE1=5&L_AMT1=6&L_DISCOUNT1=7&L_TAXTYPE1=8 Example Paymentech Salem (New Hampshire) Level 3 Visa Transaction Parameter String TRXTYPE=S&TENDER=C&PARTNER=Partner&PWD=Password&USER=User&ACCT=427533001234 5626&EXPDATE=1215&AMT=1.00&COMMENT1=0508&BILLTOFIRSTNAME=Robert&BILLTOSTREE T=123 Main St.&BILLTOZIP=94065&CVV2=426&PONUM=ABCDEFGHIJ&TAXAMT=1.00&FREIGH TAMT=2.00&DUTYAMT=3.00&SHIPTOZIP=94543&SHIPTOCOUNTRY=840&SHIPFROMZIP=94509& DISCOUNT=4.00&VATAXAMT=5.00&VATAXPERCENT=10&L_DESC1=TSYS Acquiring Solution s Pcard&L_UPC1=1&L_UOM1=2&L_QTY1=3&L_TAXAMT1=4&L_TAXRATE1=5&L_AMT1=6&L_DISC OUNT1=7&L_COMMCODE1=8&L_COST1=9&L_COST1=10

Paymentech Tampa Level 2 Purchasing Card Transaction Processing

Paymentech Tampa supports Level 2 purchasing card processing for MasterCard and Visa.

190

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

SecureNet Purchasing Card Transaction Processing

Paymentech Tampa Level 2 Parameters

Paymentech Tampa Level 2 Parameters PONUM

Description (Required) Customer reference number. Character length and limitations: 1 to 17 alphanumeric characters (Required) Sales tax. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). To qualify for Level 2 discounts, this value must not be all zeros or blank spaces. Character length and limitations: numeric (Required) Tax exempt. Character length and limitations: 1 alphanumeric character, Y or N (Required) Ship-to postal code (called zip code in the USA). Character length and limitations: 1 to 16 alphanumeric characters

TAXAMT

TAXEXEMPT

SHIPTOZIP

Example Paymentech Tampa Level 2 Visa and MasterCard Transaction Parameter String
TRXTYPE=S&TENDER=C&PWD=PWD&USER=USER&PARTNER=PARTNER&ACCT=4275330012345675& EXPDATE=1215&AMT=12.59&VERBOSITY=HIGH&BILLTOSTREET=123 Main St.&BILLTOZIP=4 9801&CVV2=248&TAXAMT=1.22&PONUM=AB12345678&SHIPTOZIP=98765&TAXEXEMPT=N

SecureNet Purchasing Card Transaction Processing

SecureNet supports MasterCard and Visa for performing Level 2 and Level 3 purchasing card transactions.

SecureNet Level 2 Parameters

SecureNet supports MasterCard and Visa for Level 2 purchasing card transactions. SecureNet indicates in the authorization response whether the credit card in the transaction is a commercial card. Based in the commercial card indicator, Payflow will format the Level 2 information in the settlement request. To get the discount rate, Level 2 parameters marked as Required in the following table must be present .

Gateway Developer Guide and Reference

19 July 2013

191

Submitting Purchasing Card Level 2 and 3 Transactions

SecureNet Purchasing Card Transaction Processing

SecureNet Level 2 Parameters Parameter PONUM Description (Required) Customer reference ID. Character length and limitations: 1 to 17 alphanumeric characters (Required) Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: numeric (Optional) Tax amount identifier. Character length and limitations: 1 alpha character, Y or N

TAXAMT

TAXEXEMPT

Example SecureNet Level 2 Visa Transaction Parameter String.

TRXTYPE=S&ACCT=4111111111111111&AMT=20.02&BILLTOCITY=Mountain View&COMMENT1 =L2 Testing&EXPDATE=1215&INVNUM=661254585&BILLTOFIRSTNAME=CardHolder First Name&BILLTOLASTNAME=CardHolder Last Name&PARTNER=PayPal&PWD=pwd&BILLTOSTATE =CA&BILLTOSTREET=123 Main St.&TAXAMT=1.01&TAXEXEMPT=N&TENDER=C&USER=user&BI LLTOZIP=94043

SecureNet Level 3 MasterCard Parameters

To qualify for Level 3 purchasing card transaction processing, the authorization response for the transaction must have the commercial card indicator set and one or more line items should be present in the delayed capture or sale request. Level 2 transaction parameters marked as Required are required for Level 3 transactions. Level 3 transactions that do not include the required Level 2 values are rejected.
IM PORT AN T :

The values required for Level 3 status vary by bank, so contact your bank for details.

SecureNet Level 2 MasterCard Parameters Required for Level 3 Line Item Transactions Parameter PONUM Description (Required) Purchase identifier. The transaction ID is sent if no value is provided. Character length and limitations: 25 alphanumeric characters (Required)Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: numeric (Optional) Local tax. Character length and limitations: 12 numeric characters

TAXAMT

LOCALTAXAMT

192

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

SecureNet Purchasing Card Transaction Processing

Parameter TAXEXEMPT

Description (Optional) Local tax incl flag. Character length and limitations: 1 alphanumeric, Y or N (Optional)National tax amount. Character length and limitations: 12 numeric characters (Required) Purchase order number/customer reference ID. The value of PNREF is sent if the INVNUM parameter is not provided. Character length and limitations: 9 alphanumeric characters SecureNet Level 3 MasterCard Extended Data

NATIONALTAXAMT

INVNUM

The parameters listed in the table below apply to Level 3 MasterCard transactions as extended data.
Parameter FREIGHTAMT Description (Optional) Freight amount. Character length and limitations: 12 numeric characters (Optional) Duty amount. Character length and limitations: 12 numeric characters (Optional) Destination country code. Character length and limitations: 3 alphanumeric characters (Optional) Alternate tax amount. Character length and limitations: 9 numeric characters

DUTYAMT

SHIPTOCOUNTRY

ALTTAXAMT

SecureNet Level 3 MasterCard Line Item Detail Records

NOT E :

For these values, n is a sequence counter that should begin with 1 and increase in sequence. Each line item should also contain quantity (L_QTY<n>) and unit price (L_COST<n>) fields.
Description (Required) Item descriptor. Character length and limitations: 35 alphanumeric characters (Optional) Product code. Character length and limitations: 12 alphanumeric characters (Required) Quantity. Character length and limitations: 12 numeric characters (Required)Unit of measure/code. Character length and limitations: 12 alphanumeric characters

Parameter L_DESCn L_UPCn L_QTYn L_UOMn

Gateway Developer Guide and Reference

19 July 2013

193

Submitting Purchasing Card Level 2 and 3 Transactions

SecureNet Purchasing Card Transaction Processing

Parameter L_TAXRATEn L_TAXTYPEn L_TAXAMTn L_DISCOUNTn

Description (Optional) Tax rate applied. Character length and limitations: 4 numeric characters (Optional) Tax type applied. Character length and limitations: 4 alphanumeric characters (Optional)Tax amount. Character length and limitations: 12 numeric characters (Optional) Discount amount. Character length and limitations: 12 numeric characters

Example SecureNet Level 3 MasterCard Transaction Parameter String TRXTYPE=S&TENDER=C&PARTNER=Partner&USER=User&PWD=Password&ACCT=552500000000 0005&EXPDATE=1215&AMT=1.00&BILLTOSTREET=5199 JOHNSON&BILLTOZIP=94588&ALTTAX AMT=1.00&CUSTVATREGNUM=11111&LOCALTAXAMT=1.00&NATIONALTAXAMT=1.00&COMMCODE= 22222&VATAXAMT=1.00&VATAXPERCENT=10&TAXEXEMPT=Y&DISCOUNT=1.00&FREIGHTAMT=1. 00&DUTYAMT=1.00&SHIPTOZIP=33333&SHIPFROMZIP=44444&SHIPTOCOUNTRY=840&ORDERDA TE=020725&L_COMMCODE1=123456789ABC&L_DESC1=Line item 1 description&L_UPC1=C BA987654321&L_QTY1=1&L_UOM1=123456789012&L_COST1=1.00&L_TAXAMT1=1.00&L_TAXR ATE1=1.00&L_DISCOUNT1=1.00&L_AMT1=1.00&L_TAXTYPE1=TT3

SecureNet Acquiring Solutions Level 3 Visa Parameters

To qualify for Level 3 purchasing card transaction processing, the authorization response for the transaction must have the commercial card indicator set and one or more line items should be present in the delayed capture or sale request. Level 2 transaction parameters marked as Required are required for Level 3 transactions. Level 3 transactions that do not include the required Level 2 values are rejected.
IM PORT AN T :

The values required for Level 3 status vary by bank, so contact your bank for details.

SecureNet Level 2 Visa Parameters for Level 3 Line Item Transactions Parameter PONUM Description (Required) Purchase identifier. The transaction ID is sent if no value is provided. Character length and limitations: 25 alphanumeric characters (Required)Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: numeric

TAXAMT

194

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

SecureNet Purchasing Card Transaction Processing

Parameter LOCALTAXAMT

Description (Optional) Local tax. Character length and limitations: 12 numeric characters (Optional) Local tax incl flag. Character length and limitations: 1 alphanumeric, Y or N (Optional)National tax amount. Character length and limitations: 12 numeric characters (Required) Purchase order number/customer reference ID. The value of PNREF is sent if the INVNUM parameter is not provided. Character length and limitations: 9 alphanumeric characters SecureNet Level 3 Visa Extended Data

TAXEXEMPT

NATIONALTAXAMT

INVNUM

The parameters listed in the table below apply to Level 3 Visa transactions as extended data.
Parameter DISCOUNT Description (Optional) Discount amount. Character length and limitations: 12 numeric characters (Optional) Freight amount. Character length and limitations: 12 numeric characters (Optional) Duty amount. Character length and limitations: 12 numeric characters (Required) Order date. The format is yymmdd with no slashes or dashes. For example, January 28, 2013 is 130128. Character length and limitations: 6 numeric characters (Optional) Destination country code. Character length and limitations: 3 alphanumeric characters (Required) Unique VAT inv reference number. Can be part of the registration data or passed with each transaction. Character length and limitations: 9 alphanumeric characters (Required) Customer VAT Registration Number. Character length and limitations: 13 alphanumeric characters (Optional)VAT/tax amount (freight/shipping). Character length and limitations: 12 numeric characters (Optional) VAT/tax rate (freight/shipping). Character length and limitations: 4 numeric characters

FREIGHTAMT

DUTYAMT

ORDERDATE

SHIPTOCOUNTRY

FREIGHTAMT

CUSTVATREGNUM

VATTAXAMT

VATTAXPERCENT

Gateway Developer Guide and Reference

19 July 2013

195

Submitting Purchasing Card Level 2 and 3 Transactions

SecureNet Purchasing Card Transaction Processing

SecureNet Level 3 Visa Line Item Detail Records

NOT E :

For these values, n is a sequence counter that should begin with 1 and increase in sequence. Each line item should also contain quantity (L_QTYn) and unit price (L_COSTn) fields.
Description (Optional) Item commodity code. Character length and limitations: 12 alphanumeric characters (Required) Item descriptor. Character length and limitations: 35 alphanumeric characters (Optional) Product code. Character length and limitations: 12 alphanumeric characters (Required) Item quantity. Character length and limitations: 12 numeric characters (Required) Unit of measure/code. Character length and limitations: 12 alphanumeric characters (Required) Unit cost. Character length and limitations: 12 numeric characters (Optional) VAT/tax amount. Character length and limitations: 12 numeric characters (Optional) VAT/tax rate. Character length and limitations: 4 numeric characters (Optional) Discount per line item. Character length and limitations: 12 numeric characters (Optional) Line-item total. Character length and limitations: 12 numeric characters

Parameter L_COMMCODEn L_DESCn L_UPCn L_QTYn L_UOMn L_COSTn L_TAXAMTn L_TAXRATEn L_DISCOUNTn L_AMTn

Example SecureNet Level 3 Visa Transaction Parameter String TRXTYPE=S&TENDER=C&PARTNER=Partner&USER=User&PWD=Password&ACCT=411111111111 1111&EXPDATE=1215&AMT=1.00&BILLTOSTREET=5199 JOHNSON&TAXAMT=1.06&BILLTOZIP= 94588&ALTTAXAMT=1.00&CUSTVATREGNUM=11111&LOCALTAXAMT=1.01&NATIONALTAXAMT=1. 02&COMMCODE=22222&VATAXAMT=1.03&VATAXPERCENT=55&TAXEXEMPT=N&DISCOUNT=.50&FR EIGHTAMT=1.00&DUTYAMT=1.00&SHIPTOZIP=33333&SHIPFROMZIP=44444&SHIPTOCOUNTRY= 840&ORDERDATE=081125&L_COMMCODE1=123456789ABC&L_DESC1=Line item 1 descripti on&L_UPC1=CBA987654321&L_QTY1=1&L_UOM1=123456789012&L_COST1=1.50&L_TAXAMT1= 1.05&L_TAXRATE1=12&L_DISCOUNT1=.50&L_AMT1=1.00&L_TAXTYPE1=TT1

196

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

TSYS Acquiring Solutions Purchasing Card Transaction Processing

TSYS Acquiring Solutions Purchasing Card Transaction Processing

TSYS Acquiring Solutions supports MasterCard and Visa for performing Level 2 and Level 3 purchasing card transactions.

TSYS Acquiring Solutions Level 2 Parameters

TSYS Acquiring Solutions supports MasterCard and Visa for Level 2 purchasing card transactions. TSYS Acquiring Solutions indicates in the authorization response whether the credit card in the transaction is a commercial card. Based in the commercial card indicator, Payflow will format the Level 2 information in the settlement request. To get the discount rate, Level 2 parameters marked as required in the following table must be present .
TSYS Acquiring Solutions Level 2 Parameters Parameter PONUM Description (Required) Customer reference ID. Character length and limitations: 1 to 17 alphanumeric characters (Required) Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: numeric (Optional) Tax amount identifier. Character length and limitations: 1 alpha character, Y or N

TAXAMT

TAXEXEMPT

Example TSYS Acquiring Solutions Level 2 Visa Transaction Parameter String.

TRXTYPE=S&ACCT=4111111111111111&AMT=20.02&BILLTOCITY=Mountain View&COMMENT1 =L2 Testing&EXPDATE=1215&INVNUM=661254585&BILLTOFIRSTNAME=CardHolder First Name&BILLTOLASTNAME=CardHolder Last Name&PARTNER=PayPal&PWD=pwd&BILLTOSTATE =CA&BILLTOSTREET=123 Main St.&TAXAMT=1.01&TAXEXEMPT=N&TENDER=C&USER=user&BI LLTOZIP=94043

TSYS Acquiring Solutions Level 3 MasterCard Parameters

To qualify for Level 3 purchasing card transaction processing, the authorization response for the transaction must have the commercial card indicator set and one or more line items should be present in the delayed capture or sale request. Level 2 transaction parameters marked as Required are required for Level 3 transactions. Level 3 transactions that do not include the required Level 2 values are rejected.

Gateway Developer Guide and Reference

19 July 2013

197

Submitting Purchasing Card Level 2 and 3 Transactions

TSYS Acquiring Solutions Purchasing Card Transaction Processing
IM PORT AN T :

The values required for Level 3 status vary by bank, so contact your bank for details.

TSYS Acquiring Solutions Level 2 MasterCard Parameters Required for Level 3 Line Item Transactions Parameter PONUM Description (Required) Purchase identifier. The transaction ID is sent if no value is provided. Character length and limitations: 25 alphanumeric characters (Required)Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: numeric (Optional) Local tax. Character length and limitations: 12 numeric characters (Optional) Local tax incl flag. Character length and limitations: 1 alphanumeric, Y or N (Optional)National tax amount. Character length and limitations: 12 numeric characters (Required) Purchase order number/customer reference ID. The value of PNREF is sent if the INVNUM parameter is not provided. Character length and limitations: 9 alphanumeric characters TSYS Acquiring Solutions Level 3 Required Parameters

TAXAMT

LOCALTAXAMT

TAXEXEMPT

NATIONALTAXAMT

INVNUM

The parameters listed in the table below apply to Level 3 transactions as extended data.
Parameter COMMCODE Description (Required) Commodity code identifier for the business. Character length and limitations: 4 alphanumeric characters (Required) The zip code of the address to which the goods are shipped. Character length and limitations: 10 alphanumeric characters (Required) The postal code (called zip code in the USA) from which shipping occurs. Character length and limitations: 10 alphanumeric characters (Required) VAT registration number. Can be part of the registration data or passed with each transaction. Character length and limitations: 20 alphanumeric characters

SHIPTOZIP

SHIPFROMZIP

VATREGNUM

TSYS Acquiring Solutions Level 3 MasterCard Extended Data

The parameters listed in the table below apply to Level 3 MasterCard transactions as extended data.

198

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

TSYS Acquiring Solutions Purchasing Card Transaction Processing

Parameter FREIGHTAMT

Description (Optional) Freight amount. Character length and limitations: 12 numeric characters (Optional) Duty amount. Character length and limitations: 12 numeric characters (Optional) Destination country code. Character length and limitations: 3 alphanumeric characters (Optional) Alternate tax amount. Character length and limitations: 9 numeric characters

DUTYAMT

SHIPTOCOUNTRY

ALTTAXAMT

TSYS Acquiring Solutions Level 3 MasterCard Line Item Detail Records

NOT E :

For these values, n is a sequence counter that should begin with 1 and increase in sequence. Each line item should also contain quantity (L_QTY<n>) and unit price (L_COST<n>) fields.
Description (Required) Item descriptor. Character length and limitations: 35 alphanumeric characters (Optional) Product code. Character length and limitations: 12 alphanumeric characters (Required) Quantity. Character length and limitations: 12 numeric characters (Required)Unit of measure/code. Character length and limitations: 12 alphanumeric characters (Optional) Tax rate applied. Character length and limitations: 4 numeric characters (Optional) Tax type applied. Character length and limitations: 4 alphanumeric characters (Optional)Tax amount. Character length and limitations: 12 numeric characters (Optional) Discount amount. Character length and limitations: 12 numeric characters

Parameter L_DESCn L_UPCn L_QTYn L_UOMn L_TAXRATEn L_TAXTYPEn L_TAXAMTn L_DISCOUNTn

Gateway Developer Guide and Reference

19 July 2013

199

Submitting Purchasing Card Level 2 and 3 Transactions

TSYS Acquiring Solutions Purchasing Card Transaction Processing

Example TSYS Acquiring Solutions Level 3 MasterCard Transaction Parameter String TRXTYPE=S&TENDER=C&PARTNER=Partner&USER=User&PWD=Password&ACCT=552500000000 0005&EXPDATE=1215&AMT=1.00&BILLTOSTREET=5199 JOHNSON&BILLTOZIP=94588&ALTTAX AMT=1.00&CUSTVATREGNUM=11111&LOCALTAXAMT=1.00&NATIONALTAXAMT=1.00&COMMCODE= 22222&VATAXAMT=1.00&VATAXPERCENT=10&TAXEXEMPT=Y&DISCOUNT=1.00&FREIGHTAMT=1. 00&DUTYAMT=1.00&SHIPTOZIP=33333&SHIPFROMZIP=44444&SHIPTOCOUNTRY=840&ORDERDA TE=020725&L_COMMCODE1=123456789ABC&L_DESC1=Line item 1 description&L_UPC1=C BA987654321&L_QTY1=1&L_UOM1=123456789012&L_COST1=1.00&L_TAXAMT1=1.00&L_TAXR ATE1=1.00&L_DISCOUNT1=1.00&L_AMT1=1.00&L_TAXTYPE1=TT3

TSYS Acquiring Solutions Level 3 Visa Parameters

To qualify for Level 3 purchasing card transaction processing, the authorization response for the transaction must have the commercial card indicator set and one or more line items should be present in the delayed capture or sale request. Level 2 transaction parameters marked as Required are required for Level 3 transactions. Level 3 transactions that do not include the required Level 2 values are rejected.
IM PORT AN T :

The values required for Level 3 status vary by bank, so contact your bank for details.

TSYS Acquiring Solutions Level 2 Visa Parameters for Level 3 Line Item Transactions Parameter PONUM Description (Required) Purchase identifier. The transaction ID is sent if no value is provided. Character length and limitations: 25 alphanumeric characters (Required)Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: numeric (Optional) Local tax. Character length and limitations: 12 numeric characters (Optional) Local tax incl flag. Character length and limitations: 1 alphanumeric, Y or N (Optional)National tax amount. Character length and limitations: 12 numeric characters (Required) Purchase order number/customer reference ID. The value of PNREF is sent if the INVNUM parameter is not provided. Character length and limitations: 9 alphanumeric characters

TAXAMT

LOCALTAXAMT

TAXEXEMPT

NATIONALTAXAMT

INVNUM

200

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

TSYS Acquiring Solutions Purchasing Card Transaction Processing

TSYS Acquiring Solutions Level 3 Required Parameters

The parameters listed in the table below apply to Level 3 transactions as extended data.
Parameter COMMCODE Description (Required) Commodity code identifier for the business. Character length and limitations: 4 alphanumeric characters (Required) The zip code of the address to which the goods are shipped. Character length and limitations: 10 alphanumeric characters (Required) The postal code (called zip code in the USA) from which shipping occurs. Character length and limitations: 10 alphanumeric characters (Required) VAT registration number. Can be part of the registration data or passed with each transaction. Character length and limitations: 20 alphanumeric characters

SHIPTOZIP

SHIPFROMZIP

VATREGNUM

TSYS Acquiring Solutions Level 3 Visa Extended Data

The parameters listed in the table below apply to Level 3 Visa transactions as extended data.
Parameter DISCOUNT Description (Optional) Discount amount. Character length and limitations: 12 numeric characters (Optional) Freight amount. Character length and limitations: 12 numeric characters (Optional) Duty amount. Character length and limitations: 12 numeric characters (Required) Order date. The format is yymmdd with no slashes or dashes. For example, January 28, 2013 is 130128. Character length and limitations: 6 numeric characters (Optional) Destination country code. Character length and limitations: 3 alphanumeric characters (Required) Unique VAT inv reference number. Can be part of the registration data or passed with each transaction. Character length and limitations: 9 alphanumeric characters (Required) Customer VAT Registration Number. Character length and limitations: 13 alphanumeric characters (Optional)VAT/tax amount (freight/shipping). Character length and limitations: 12 numeric characters (Optional) VAT/tax rate (freight/shipping). Character length and limitations: 4 numeric characters

FREIGHTAMT

DUTYAMT

ORDERDATE

SHIPTOCOUNTRY

FREIGHTAMT

CUSTVATREGNUM

VATTAXAMT

VATTAXPERCENT

Gateway Developer Guide and Reference

19 July 2013

201

Submitting Purchasing Card Level 2 and 3 Transactions

TSYS Acquiring Solutions Purchasing Card Transaction Processing

TSYS Acquiring Solutions Level 3 Visa Line Item Detail Records

NOT E :

For these values, n is a sequence counter that should begin with 1 and increase in sequence. Each line item should also contain quantity (L_QTYn) and unit price (L_COSTn) fields.
Description (Optional) Item commodity code. Character length and limitations: 12 alphanumeric characters (Required) Item descriptor. Character length and limitations: 35 alphanumeric characters (Optional) Product code. Character length and limitations: 12 alphanumeric characters (Required) Item quantity. Character length and limitations: 12 numeric characters (Required) Unit of measure/code. Character length and limitations: 12 alphanumeric characters (Required) Unit cost. Character length and limitations: 12 numeric characters (Optional) VAT/tax amount. Character length and limitations: 12 numeric characters (Optional) VAT/tax rate. Character length and limitations: 4 numeric characters (Optional) Discount per line item. Character length and limitations: 12 numeric characters (Optional) Line-item total. Character length and limitations: 12 numeric characters

Parameter L_COMMCODEn L_DESCn L_UPCn L_QTYn L_UOMn L_COSTn L_TAXAMTn L_TAXRATEn L_DISCOUNTn L_AMTn

Example TSYS Acquiring Solutions Level 3 Visa Transaction Parameter String TRXTYPE=S&TENDER=C&PARTNER=Partner&USER=User&PWD=Password&ACCT=411111111111 1111&EXPDATE=1215&AMT=1.00&BILLTOSTREET=5199 JOHNSON&TAXAMT=1.06&BILLTOZIP= 94588&ALTTAXAMT=1.00&CUSTVATREGNUM=11111&LOCALTAXAMT=1.01&NATIONALTAXAMT=1. 02&COMMCODE=22222&VATAXAMT=1.03&VATAXPERCENT=55&TAXEXEMPT=N&DISCOUNT=.50&FR EIGHTAMT=1.00&DUTYAMT=1.00&SHIPTOZIP=33333&SHIPFROMZIP=44444&SHIPTOCOUNTRY= 840&ORDERDATE=130125&L_COMMCODE1=123456789ABC&L_DESC1=Line item 1 descripti on&L_UPC1=CBA987654321&L_QTY1=1&L_UOM1=123456789012&L_COST1=1.50&L_TAXAMT1= 1.05&L_TAXRATE1=12&L_DISCOUNT1=.50&L_AMT1=1.00&L_TAXTYPE1=TT1

202

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

Vantiv Purchasing Card Transaction Processing

Vantiv Purchasing Card Transaction Processing

The following parameters are recommended to obtain the best rates for Level 2 and Level 3 purchasing card transactions with Vantiv.

Vantiv Purchasing Parameters

Field SHIPTOCOUNTRY Description (Optional) Destination country code. Visa and MasterCard are different. Character length and limitations: 3 alpha characters (Optional) Discount amount on total sale Character length and limitations: 10 currency characters (Optional) Sometimes called import tax. If the currency uses a decimal, then the value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: 10 currency characters Character length and limitations: 10 currency characters (Optional) Purchase order number / merchant-related data. Character length and limitations: 25 alphanumeric characters, provides best rate when used (Optional) The postal code (called zip code in the USA) from which shipping occurs. Character length and limitations: 9 numeric characters, provides best rate when used (Optional) Ship to postal code (called zip code in the USA). Character length and limitations: 9 numeric characters, provides best rate when used (Optional) Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). Character length and limitations: 10 currency characters

DISCOUNT

DUTYAMT

FREIGHTAMT PONUM

SHIPFROMZIP

SHIPTOZIP

TAXAMT

Vantiv Purchasing Card Line Item Parameters

Line item data (Level 3) describes the details of the item purchased and can be passed for each transaction. The convention for passing line item data in name-value pairs is that each namevalue starts with L_ and ends with n where n is the line item number. For example L_QTY0=1 is the quantity for line item 0 and is equal to 1, with n starting at 0. In addition, the SHIPFROMZIP parameter is required for Level 3 transactions.

Gateway Developer Guide and Reference

19 July 2013

203

Submitting Purchasing Card Level 2 and 3 Transactions

WorldPay Purchasing Cards Transaction Processing

Vantiv Line Item Parameters Field L_QTYn L_COMMCODEn L_DESCn L_UOMn L_COSTn L_UPCn L_DISCOUNTn L_AMTn Description (Required) Quantity (whole units only). Character length and limitations: 10 numeric characters (Optional) Item commodity code. Character length and limitations: 12alphanumeric characters (Optional) Item description. Character length and limitations: 35 alphanumeric characters (Optional) Item unit of measure. Character length and limitations: 3 alpha characters (Optional) Cost per item, excluding tax. Character length and limitations: 10 currency characters (Optional) Supplier specific product code. Character length and limitations: 12 alphanumeric characters (Optional) Discount per line item. Character length and limitations: 10 currency characters (Optional) Total line item amount including tax and discount. + for debit, - for credits. Character length and limitations: 10 currency characters (Optional) Line item tax amount. Character length and limitations: 10 currency characters

L_TAXAMTn

WorldPay Purchasing Cards Transaction Processing

The following parameters are recommended to obtain the best rates for Level 2 and Level 3 purchasing card transactions with WorldPay.

WorldPay Level 2 Parameters

Pass the following WorldPay Level 2 parameters to get the discount rate.
WorldPay Level 2 parameters Level 2 Parameters ALTTAXAMT Description (Optional) Alternate tax amount. Character length and limitations: 8 alphanumeric characters

204

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

WorldPay Purchasing Cards Transaction Processing

Level 2 Parameters COMMCODE

Description (Optional) Summary commodity code identifier for the business. Character length and limitations: 4 alphanumeric characters (Optional) Country code. Character length and limitations: 3 alphanumeric characters (Optional) Generic data the merchant can pass to the WorldPay processor. Character length and limitations: 95 alphanumeric characters (Optional) Purchase order number. Character length and limitations: 95 alphanumeric characters (Optional) Customer number. Character length and limitations: 95 alphanumeric characters (Optional) Discount amount on total sale. Character length and limitations: 10 currency characters (Optional) Account holders driver license name. Character length and limitations: 95characters (Optional) Account holders driver license number. Character length and limitations: 95 alphanumeric characters (Optional) Account holders date of birth in the format MMDDYYYY. For example, July 28, 2011 is represented as: 07282011 Character length and limitations: 8 characters (Optional) Sometimes called import tax. Character length and limitations: The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). 10 currency characters (Optional) Total freight amount. Character length and limitations: The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). 10 currency characters (Optional) Merchant invoice number for the transaction. Character length and limitations: 95 alphanumeric characters (Optional) Description of product. Character length and limitations: 50 alphanumeric characters (Optional) Merchant invoice number. Character length and limitations: 25 alphanumeric characters (Optional) Merchant value added tax number. Character length and limitations: 95 alphanumericcharacters

COUNTRYCODE

CUSTDATA

CUSTOMERID

CUSTOMERNUMBER

DISCOUNT

DLNAME

DLNUM

DOB

DUTYAMT

FREIGHTAMT

INVNUM

MERCHANTDESCR

MERCHANTINVNUM

MERCHANTVATNUM

Gateway Developer Guide and Reference

19 July 2013

205

Submitting Purchasing Card Level 2 and 3 Transactions

WorldPay Purchasing Cards Transaction Processing

Level 2 Parameters MERCHANTZIP

Description (Optional) 5- to 9-digit zip (postal) code excluding spaces, dashes, and nonnumeric 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 (Optional) Miscellaneous data. Character length and limitations: 95 alphanumeric characters (Required) Order date. The format is MMDDYY with no slashes or dashes. For example, July 28, 2011 is 072811. Character length and limitations: 6 numeric characters (Optional) Purchase order number. Character length and limitations: 25 alphanumeric characters (Optional) Ship to postal code (called zip code in the USA). Character length and limitations: 9 numeric characters (Optional) Sales tax. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56). To qualify for Level 2 discounts, this value must not be all zeros or blank spaces. Character length and limitations: numeric (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: 1alpha character (Optional) Value added tax invoice number. Character length and limitations: 95 alphanumeric characters (Optional) Customer valued added tax number. Character length and limitations: 95 alphanumeric characters (Optional) VAT/tax amount (freight/shipping). Character length and limitations: 12 numeric characters (Optional) VAT/tax rate (freight/shipping). Character length and limitations: 4 numeric characters

MISCDATA

ORDERDATE

PONUM

SHIPTOZIP

TAXAMT

TAXEXEMPT

VATINVNUM

VATNUM

VATTAXAMT

VATTAXRATE

WorldPay Level 3 Parameters

Pass the following WorldPay Level 3 parameters to get the discount rate.

206

19 July 2013

Gateway Developer Guide and Reference

Submitting Purchasing Card Level 2 and 3 Transactions

WorldPay Purchasing Cards Transaction Processing

WorldPay Level 3 parameters Level 3 Parameters L_ALTTAXAMTn L_ALTTAXRATEn L_ALTTAXIDn L_EXTAMTn L_TAXTYPEn L_COMMCODEn L_DESCn L_AMTn Description (Optional) Alternate tax amount for this item. Character length and limitations: 8 numeric characters plus decimal: XXXX.XX (Optional) Alternate tax rate for this item. Character length and limitations: 4 numeric characters plus decimal: XX.XX (Optional) Alternate tax identifier for this item. Character length and limitations: 95 alphanumeric characters (Optional) Extended item amount. Character length and limitations: 8 numeric characters (Optional) Tax type applied. Character length and limitations: 4 alphanumeric characters (Optional) Item commodity code. Character length and limitations: 35 alphanumeric characters (Optional) Item description. Character length and limitations: 10 currency characters (Optional) Total line item amount including tax. + for debit, - for credits 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 (Optional) Item's supplier stock keeping unit (SKU) number or product code. Character length and limitations: 8 numeric characters (Required) Quantity (whole units only). Character length and limitations: 10 numeric characters (Optional) Service code. Character length and limitations: 1 alphanumeric character (Optional) Item freight 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. 10 currency characters (Optional) Item unit of measure. Character length and limitations: 3 alpha characters (Optional) Item 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 (Optional) Tax rate for this item. Character length and limitations: 4 numeric characters plus decimal:XXXX

L_SKUn L_QTYn L_CARRIERSERVICELEV ELCODEn L_COSTn

L_UOMn L_TAXAMTn

L_TAXRATEn

Gateway Developer Guide and Reference

19 July 2013

207

Submitting Purchasing Card Level 2 and 3 Transactions

WorldPay Purchasing Cards Transaction Processing

208

19 July 2013

Gateway Developer Guide and Reference

Payflow Header Parameters

This section includes information on the Payflow header parameters. These header parameters can be used to bypass Payflow to send a request message directly to PayPal. They can also be used to post transactions to the Payflow servers directly without installing an SDK. This section includes: Sending Requests Directly to PayPal Bypassing Payflow on page 209 Posting Transactions Directly Without the Payflow SDK on page 210

Sending Requests Directly to PayPal Bypassing Payflow

Payflow will ignore the request parameters you pass and will forward them to PayPal when you declare PAYPAL-NVP=Y in the request header. Declaring PAYPAL-NVP=Y in the request header is required when passing negative discount amounts to PayPal through Payflow. Please note that passing PAYPAL-NVP=Y in the request header changes the format of the response message you receive from Payflow. For example, if PAYPAL-NVP=Y is NOT declared in the header, the Payflow response message is formatted as follows: RESULT=0&RESPMSG=Approved&TOKEN=EC868676987J8393917&CORRELATIONID=5f817d830101 If the request header PAYPAL-NVP=Y is declared, the response returned from Payflow includes bracketed numbers next to the names of the response parameters. These bracketed numbers are length tags indicating the length of the values returned. The following is a response message that contains length tags: RESULT=0&RESPMSG=Approved&TOKEN[20]=EC97J718043X120051H&TIMESTAMP[20]=2012-1011T15:19:37Z&CORRELATIONID[13]=274f8d4493dbe&ACK[7]=Success&VERSION[ 4]=92.0&BUILD[7]=3893058 You can also use length tags in the Payflow request message to pass the special characters of "&" and "=" in the values sent. See Using Special Characters In Values on page 51 for more information.
Express Checkout for Payflow

For information on using the PayPal Express Checkout API with Payflow, see the Express Checkout for Payflow integration guide.

Gateway Developer Guide and Reference

19 July 2013

209

Payflow Header Parameters

Posting Transactions Directly Without the Payflow SDK

Posting Transactions Directly Without the Payflow SDK

The Payflow SDK is recommended for .NET and Java users, to simplify the Payflow integration. Developers who prefer to write code in other programming languages can go to the PayPal Labs integration wizard web site (https://www.paypallabs.com/integrationwizard/index.php.). The wizard generates customizable code samples in languages such as PHP. Developers also have the option to post transactions directly to the Payflow servers using the Payflow message protocol, without the need to install an SDK. This section describes the HTTP headers that are required to post transactions directly to the Payflow servers.

The Payflow Message Protocol

What is the Payflow message protocol and what are its advantages? PayPals Payflow message protocol is an HTTP-compatible protocol for transactions. The HTTP-compliant implementation of this protocol has the following goals:

It enhances flexibility to developers integrating with the Payflow Service. Merchants can use the protocol in either of these ways: Using a Payflow SDK such as .NET or Java that uses this protocol. Integrating this protocol directly into your own client application without using an SDK. It increases reliability through adherence to open standards. Built-in tools to prevent duplicate transactions and authorizations.

The Payflow message protocol provides the underlying transport for application-level transactions, using either the Payflow name-value pair or XMLPay 2.0 format. All transaction data as documented in this guide is embedded in the body of a standard HTTPS POST and POSTed to the URLs specified.

What is the disadvantage of building your own integration? Since you are building your own integration, you will need to add your own error handling, retry logic and duplicate transaction handling within your code.
NOT E :

If you prefer not to write your own client, you can use the .NET SDK, which can also be used with classic ASP, or the Java SDK if appropriate. See Payflow SDK on page 49 for more information about the SDKs.

What code changes are required when migrating from a previous Payflow SDKs to this service? The Payflow HTTPS service uses the same name-value-pair parameters or XMLPay schema as found in the current SDKs. The the only code change needed is the way you communicate with the Payflow servers. Instead of using an SDK to send the data, you will use the methods

210

19 July 2013

Gateway Developer Guide and Reference

Payflow Header Parameters

Posting Transactions Directly Without the Payflow SDK

available in your programming language of choice to send the data via HTTPS. For example, if you use PHP, you might choose to use cURL.

Payflow Message Protocol Headers

In addition to the Payflow parameters that you pass in your request, you must set the request headers described in the following table.

Gateway Developer Guide and Reference

19 July 2013

211

Payflow Header Parameters

Posting Transactions Directly Without the Payflow SDK

Required Payflow Headers Header Name X-VPS-REQUEST-ID Description (Required) A unique identifier for each request, whether the request is a single name-value transaction or an XMLPay 2.0 document with multiple transactions. This identifier is associated with all the transactions in that particular request. X-VPS-REQUEST-ID is made up of 1 to 32 printable characters. You must provide the X-VPS-REQUEST-ID value in the transaction request. The server uses the X-VPS-REQUEST-ID to check for duplicate transaction requests. When a transaction request is received, the server checks the requests table to see if the X-VPS-REQUEST-ID has been used before by this merchant. If the X-VPS-REQUEST-ID has been used before, the server views it as a retry transaction and the transaction is treated as a duplicate. The response to the original transaction request is returned and DUPLICATE=1 is appended to the response indicating that this transaction is a duplicate. In Manager, you will see these DUPLICATE transactions with a TENDER type of N.
I MP O R TAN T :

If you send in a NEW transaction with a previously used XVPS-REQUEST-ID, the server ignores the new data and returns the response to the original transaction associated with that XVPS-REQUEST-ID.

It is VERY IMPORTANT that you check for DUPLICATE=1 and if you receive it and the transaction is not a re-attempt of the original request of a failed transaction, you must change the Request ID. If the X-VPS-REQUEST-ID has not been used before, the server stores the XVPS-REQUEST-ID to ensure that the X-VPS-REQUEST-ID is not reused and then runs the associated transactions. Duplicate checking is designed for shortterm retries (a few minutes to a few hours after the original transaction). The XVPS-REQUEST-ID is stored for a minimum of 7 to 8 days; however, retries should not be sent so long after the original transaction.
N O TE :

Any transaction with an ID older than 8 days will be treated as a new transaction.

The X-VPS-REQUEST-ID check is only available if the database is up and available. If for some reason the database is down, transactions (authorizations and sales) will continue to be processed as normal; however, DUPLICATE=-1 (negative one) will be returned to alert you that the database is down and there is no duplicate check being performed.
N O TE :

Buyer Authentication: E-Verify Enrollment, Z-Validate Authentication transactions and PayPal Express Checkout: SetExpressCheckout and GetExpressCheckout transactions do not use duplicate suppression and will not return DUPLICATE=1

X-VPS-CLIENT-TIMEOUT

(Required) Time-out value in seconds. A transaction times out if the elapsed time between ending the original transaction request and receiving the transaction response exceeds the value of X-VPS-CLIENT-TIMEOUT. The default value is 45.

212

19 July 2013

Gateway Developer Guide and Reference

Payflow Header Parameters

Posting Transactions Directly Without the Payflow SDK

Standard HTTP Headers Required Header Name Connection Content-Length Content-Type Description State of the connection. The server returns the value close to close the connection after the response is sent. (Required) Size of message body. (Required) Provide one of the following values: text/name value, transaction request body is in name-value pair format. text/xml, transaction request body is in XMLPay 2.0 format. (Required) Provide one of the two host URLs: Production: payflowpro.paypal.com Pilot: pilot-payflowpro.paypal.com

Host

Transaction Message
The transaction message communicates the initial transaction data to the server. It is made up of the transaction request and response. URLs for Sending Messages Use the following URLs for sending transactions to PayPals Payflow Production servers: Production (Live): https://payflowpro.paypal.com/ Pilot (Test): https://pilot-payflowpro.paypal.com/ Transaction Request The transaction request consists of a transaction request header and body. Name-Value Pair Transaction Request Header
Content-Type: text/name value Content-Length: 233 Connection: close Host: payflowpro.verisign.com X-VPS-REQUEST-ID: [See Required Payflow Headers] X-VPS-CLIENT-TIMEOUT: 45 X-VPS-VIT-[See Integrator-Provided Data] X-VPS-VIT-[See Integrator-Provided Data]

The following is an example of a transaction request header associated with a message in name-value format. For XMLPay, it would follow the same format except the content-type would be text/xml and the body of the request and response would contain the XML document.

Gateway Developer Guide and Reference

19 July 2013

213

Payflow Header Parameters

Posting Transactions Directly Without the Payflow SDK

Name-Value Pair Transaction Request Body The transaction request body contains the transaction information. The following is an example transaction request body in name-value pair format.
TRXTYPE[1]=S&ACCT[16]=5105105105105100&EXPDATE[4]=0109&TENDER[1]=C&INVNUM[8 ]=INV12345&AMT[5]=25.12&PONUM[7]=PO12345&STREET[23]=123 Main St.&ZIP[5]=12345&USER[6]=jsmith&VENDOR[6]=jsmith&PARTNER[6]=PayPal&PWD[8]=t esting1
NOT E :

The bracketed numbers are length tags which allow you to use the special characters of "&" and "=" in the value sent. See Using Special Characters In Values on page 51 for more information.

The Request Body should NOT be URL-encoded. Pass the data as a standard data and use the length tags if needed. Transaction Response The transaction response consists of a transaction response header and body. Name-Value Pair Transaction Response Header The following is an example transaction response header associated with a message in namevalue format.
Connection: close Server: VPS-3.028.00 Date: Mon, 16 May 2005 22:48:06 GMT Content-Type: text/name value Content-Length: 145 X-VPS-REQUEST-ID: [Same ID as sent]

Name-Value Pair Transaction Response Body The transaction response body contains the response to the request. The following is an example response body in name-value format.
RESULT=0&PNREF=V53A0A30B542&RESPMSG=Approved&AUTHCODE=882PNI&AVSADDR=X&AVSZ IP=X&IAVS=X&PREFPSMSG=No Rules Triggered&POSTFPSMSG=No Rules Triggered

Integrator-Provided Data
These headers are extensions to the Payflow message protocol. The extension parameters describe the specific version of a client and the clients environment. Send the applicable parameters to PayPal in the transaction request headers.
NOT E :

The parameters in this section are not required but it is highly recommended you send them.

214

19 July 2013

Gateway Developer Guide and Reference

Payflow Header Parameters

Posting Transactions Directly Without the Payflow SDK

Payflow Recommended Headers Header Name X-VPS-VIT-INTEGRATION-PRODUCT Description Identifies the integration product that calls the PayPal server. Format: String Examples: iPayment, ColdFusion, MIVA, shopping cart Default Value: Blank Version of the software as defined by the integrator/vendor. Limited to the major version and one digit of the minor version (can include alphanumeric characters, not just digits). Format: String <Major Version>.<Minor Version> Examples: 1.1, 4.5, 10.0, Linux2.1 Default Value: Blank Name of operating system on which the client is running. Format: String Examples: Linux, SunOS, Windows 2000, Windows NT, Windows XP, Mac OS X, Free BSD Default Value: Blank Version of operating system on which the client is running. Format: String XXX.X Example: 2.4 Default Value: Blank Version of runtime environment of the language in which the client is written and is running. Format: String XXX.XE Examples: 10.1, 2.5 Default Value: Blank

X-VPS-VIT-INTEGRATION-VERSION

X-VPS-VIT-OS-NAME

X-VPS-VIT-OS-VERSION

X-VPS-VIT-RUNTIME-VERSION

Gateway Developer Guide and Reference

19 July 2013

215

Payflow Header Parameters

Posting Transactions Directly Without the Payflow SDK

216

19 July 2013

Gateway Developer Guide and Reference

E
NOT E :

VERBOSITY: Processor-Specific Transaction Results

Set the VERBOSITY parameter to HIGH to view the processor's raw response values and additional values. This setting returns multiple parameters. Select only the returned parameters that you want to handle and disregard the rest. VERBOSITY is being deprecated in future Gateway releases.

Gateway Developer Guide and Reference

19 July 2013

217

VERBOSITY: Processor-Specific Transaction Results

218

19 July 2013

Gateway Developer Guide and Reference

F
NOT E :

ISO Country Codes

The Gateway API uses the International Standards Organization (ISO) 3166-1 numeric country codes in the following fields: BILLTOCOUNTRY and SHIPTOCOUNTRY. For a complete list of the current officially assigned ISO 3166-1 numeric country codes, refer to:
http://en.wikipedia.org/wiki/ISO_3166-1_numeric

If PayPal is your acquirer, refer instead to the Countries and Regions Supported by PayPal on page 83.

Gateway Developer Guide and Reference

19 July 2013

219

ISO Country Codes

220

19 July 2013

Gateway Developer Guide and Reference

Codes Used by FDMS South Only

The following codes are used by FDMS South only. MasterCard Country Codes for FDMS South Only on page 221 Visa Country Codes on page 228 Units of Measure on page 235

MasterCard Country Codes for FDMS South Only

ALBANIA ALGERIA AMERICAN SAMOA ANDORRA ANGOLA ANGUILLA ANTARCTICA ANTIGUA APHGANISTAN ARGENTINA ARMENIA ARUBA AUSTRALIA AUSTRIA AZERBAIJAN BAHAMAS BAHRAIN BANGLADESH BARBADOS BELARUS BELGIUM ALB DZA ASM AND AGO AIA ATA ATG AFG ARG ARN ABW AUS AUT AZE BHS BHR BGD BRB BLR BEL

Gateway Developer Guide and Reference

19 July 2013

221

Codes Used by FDMS South Only

MasterCard Country Codes for FDMS South Only

BELIZE BENIN BERMUDA BHUTAN BOLIVIA BOSNIA AND HERZEGOVINA BOTSWANA BOUVET ISLAND BRAZIL BRITISH INDIAN OCEAN TERRITORY BRUNEI BULGARIA BURKINA FASO BURUNDI CAMBODIA CANADA CAPE VERDE CAYMAN ISLANDS CENTRAL AFRICAN REPUBLIC CHAD CHILE CHINA CHRISTMAS ISLAND CMEROON, UNITED REP. COCOS (KEELING) ISLANDS COLOMBIA COMOROS CONGO COOK ISLANDS COSTA RICA COTED'IVOIRE CROATIA

BLZ BEN BMU BTN BOL BIH BWA BVT BRA IOT BRN BGR BFA BDI KHM CAN CPV CYM CAF TCD CHL CHN CXR CMR CCK COL COM GOG COK CRI CIV HRV

222

19 July 2013

Gateway Developer Guide and Reference

Codes Used by FDMS South Only

MasterCard Country Codes for FDMS South Only

CYPRUS CZECH REPUBLIC DENMARK DJIBOUTI DOMINICA DOMINICAN REPUBLIC EL SALVADOR EQUATORIAL GUINEA ESTONIA ETHIOPIA FAEROE ISLANDS FALKLAND ISLANDS (MALVINAS) FIJI FINLAND FRANCE FRENCH GUIANA FRENCH POLYNESIA FRENCH SOUTHERN TERRITORIES GABON GAMBIA GEORGIA GERMAN DEMOCRATIC REP GERMANY GHANA GIBRALTAR GREECE GREENLAND GRENADA GUADALUPE GUAM GUATEMALA GUINEA

CYP CZE DNK DJI DMA DOM SLV GNQ EST ETH FRO FLK FJI FIN FRA GUF PYF ATF GAB GMB GEO DDR DEU GHA GIB GRC GRL GRD GLP GUM GTM GIN

Gateway Developer Guide and Reference

19 July 2013

223

Codes Used by FDMS South Only

MasterCard Country Codes for FDMS South Only

GUINEA-BISSAU GUYANA HAITI HEARD AND MCDONALD ISLANDS HONDURAS HONG KONG HUNGARY ICELAND INDIA INDONESIA IRAN IRAQ IRELAND ISRAEL ITALY JAMAICA JAPAN JORDAN KAZAKHSTAN KENYA KOREA, REPUBLIC OF KUWAIT KYRGYZSTAN LAO PEOPLES DEMOCRATIC LATVIA LEBANON LESOTHO LIBERIA LIBYAN ARAB JAMAHIRIYA LIECHTNSTIEN LITHUANIA LUXEMBOURG

GNB GUY HTI HMD HND HKG HUN ISL IND IDN IRN IRQ IRL ISR ITA JAM JPN JOR KAZ KEN KOR KWT KGZ LAO LVA LBN LSO LBR LBY LIE LTU LUX

224

19 July 2013

Gateway Developer Guide and Reference

Codes Used by FDMS South Only

MasterCard Country Codes for FDMS South Only

MACAU MALAYSIA MALDIVES MALI MALTA MANACO MARSHALL ISLANDS MARTINIQUE MAURITANIA MAURITIUS MEXICO MICRONESIA MOLDOVA MONGOLIA MONTSERRAT MOROCCO MOZAMBIQUE MYANMAR NAMIBIA NAURU NEGEL NEPAL NETHERLANDS NETHERLANDS ANTILLES NEW CALEDONIA NEW ZEALAND NICARAGUA NIGER NIGERIA NIUE NORFOLK ISLAND NORTHERN MARIANA ISLAND

MAC MYS MDV MLI MLT MCO MHL MTQ MRT MUS MEX FSM MDA MNG MSR MAR MOZ MMR NAM NRU SEN NPL NLD ANT NCL NZL NIC NER NGA NIU NFK MNP

Gateway Developer Guide and Reference

19 July 2013

225

Codes Used by FDMS South Only

MasterCard Country Codes for FDMS South Only

NORWAY OMAN PAKISTAN PALAU PANAMA PAPUA NEW GUINEA PARAGUAY PERU PHILIPPINES PITCAIRN ISLAND POLAND PORTUGAL PUERTO RICO QATAR REUNION ROMANIA RUSSIAN FEDERATION RWANDA SAMOA SAN MARINO SAN TOME AND PRICIPEL SAUDI ARABIA SEYCHELLES SIERRA LEONA SINGAPORE ST. HELENA ST. KITTS-NEVIS-ANGUILLA ST. LUCIA ST. PIERRE AND MIQUELON ST. VINCENT AND THE GRENADINES SUDAN SURINAME

NOR OMN PAK PLW PAN PNG PRY PER PHI PCN POL PRT PRI QAT REU ROM RUS RWA WSM SMR STP SAU SYC SLE SGP SHN KNA LCA SPM VCT SDN SUR

226

19 July 2013

Gateway Developer Guide and Reference

Codes Used by FDMS South Only

MasterCard Country Codes for FDMS South Only

SVALBARD AND JAN MAYEN ISLANDS SWAZILAND SWEDEN SWITZERLAND SYRIAN ARAB REPUBLIC TAIWAN, PROVIDENCE OF CHINA TAJIKISTAN TANZANIA, UNITED REPUBLIC THAILAND TOGO TOKELAU TONGA TRINIDAD AND TOBAGO TUNISIA TURKEY TURKMENISTAN TURKS AND CAICOS ISLANDS TUVALU U.S. MINOR OUTLYING ISL. UGANDA UKRAINE UNITED ARAB EMIRATES UNITED KINGDOM UNITED STATES URUGUAY UZBEKISTAN VANUATU VATICAN CITY STATE VENEZUELA VIETNAM VIRGIN ISLANDS BRITISH VIRGIN ISLANDS US

SJM SWZ SWE CHE SYR TWN TJK TZA THA TGO TKL TON TTO TUN TR TM TC TUV UMI UGA UKR ARE GBR USA URY UZB VUT VAT VEN VNM VGB VIR

Gateway Developer Guide and Reference

19 July 2013

227

Codes Used by FDMS South Only

Visa Country Codes

WALLIS AND FUTUNA IS WESTERN SAHARA YEMEN YUGOSLAVIA ZAIRE ZAMBIA ZIMBABWE

WLF ESH YEM YUG ZAR ZMB RHO

Visa Country Codes

ALBANIA ALGERIA AMERICAN SAMOA ANDORRA ANGOLA ANGUILLA ANTARCTICA ANTIGUA APHGANISTAN ARGENTINA ARMENIA ARUBA AUSTRALIA AUSTRIA AZERBAIJAN BAHAMAS BAHRAIN BANGLADESH BARBADOS BELARUS BELGIUM AL DZ AS AD AO AI AQ AG AF AR AM AW AU AT AZ BS BH BD BB BY BE

228

19 July 2013

Gateway Developer Guide and Reference

Codes Used by FDMS South Only

Visa Country Codes

BELIZE BENIN BERMUDA BHUTAN BOLIVIA BOSNIA AND HERZEGOVINA BOTSWANA BOUVET ISLAND BRAZIL BRITISH INDIAN OCEAN TERRITORY BRUNEI BULGARIA BURKINA FASO BURUNDI CAMBODIA CANADA CAPE VERDE CAYMAN ISLANDS CENTRAL AFRICAN REPUBLIC CHAD CHILE CHINA CHRISTMAS ISLAND CMEROON, UNITED REP. COLOMBIA COMOROS CONGO COOK ISLANDS COSTA RICA COTED'IVOIRE CROATIA CYPRUS

BZ BJ BM BT BO BA BW BV BR IO BN BG BF BI KH CA CV KY CF TD CL CN CX CM CO KM CG CK CR CI HR CY

Gateway Developer Guide and Reference

19 July 2013

229

Codes Used by FDMS South Only

Visa Country Codes

CZECH REPUBLIC DENMARK DJIBOUTI DOMINICA DOMINICAN REPUBLIC EAST TIMOR ECUADOR EGYPT EL SALVADOR EQUATORIAL GUINEA ESTONIA ETHIOPIA FAEROE ISLANDS FALKLAND ISLANDS (MALVINAS) FIJI FINLAND FRANCE FRENCH GUIANA FRENCH METROPOLITAN FRENCH POLYNESIA FRENCH SOUTHERN TERRITORIES GABON GAMBIA GEORGIA GERMANY GHANA GIBRALTER GREECE GREENLAND GRENADA GUADALUPE GUAM

CZ DK DJ DM DO TP EC EG SV GQ EE ET FK FK FJ FI FR GF FX PF TF GA GM GE DE GH GI GR GL GD GP GU

230

19 July 2013

Gateway Developer Guide and Reference

Codes Used by FDMS South Only

Visa Country Codes

GUATEMALA GUINEA GUINEA-BISSAU GUYANA HAITI HEARD AND MCDONALD ISLANDS HONDURAS HONG KONG HUNGARY ICELAND INDIA INDONESIA IRAN IRAQ IRELAND ISRAEL ITALY JAMAICA JAPAN JORDAN KAZAKHSTAN KENYA KIRIBATI KOREA, REPUBLIC OF KUWAIT KYRGYZSTAN LAO PEOPLES DEMOCRATIC LATVIA LEBANON LESOTHO LIBERIA LIBYAN ARAB JAMAHIRIYA

GT GN GW GY HT HM HN HK HU IS IN ID IR IQ IE IL IT JM JP JO KZ KE KI KR KW KG LA LV LB LS LR LY

Gateway Developer Guide and Reference

19 July 2013

231

Codes Used by FDMS South Only

Visa Country Codes

LIECHTNSTIEN LITHUANIA LUXEMBOURG MACAU MACEDONIA MADAGASCAR MALAWI MALAYSIA MALDIVES MALI MALTA MANACO MARSHALL ISLANDS MARTINIQUE MAURITANIA MAURITIUS MAYOTTE MEXICO MICRONESIA MOLDOVA MONGOLIA MONTSERRAT MOROCCO MOZAMBIQUE MYANMAR NAMIBIA NAURU NEPAL NETHERLANDS NETHERLANDS ANTILLES NEW CALDONIA NEW ZEALAND

LI LT LU MO MK MG MW MY MV ML MT MC MH MQ MR MU YT MX FM MD MN MS MA MZ MM NA NR NP NL AN NC NZ

232

19 July 2013

Gateway Developer Guide and Reference

Codes Used by FDMS South Only

Visa Country Codes

NICARAGUA NIGER NIGERIA NIUE NORFOLK ISLAND NORTHERN MARIANA ISLAND NORWAY OMAN PAKISTAN PALAU PANAMA PAPUA NEW GUINEA PARAGUAY PERU PHILIPPINES PITCAIRN ISLAND POLAND PORTUGUL PUERTO RICO QATAR REUNION ROMANIA RUSSIAN FEDERATION RWANDA SAMOA SAN MARINO SAN TOME AND PRICIPEL SAUDI ARABIA SENEGAL SEYCHELLES SIERRA LEONA SINGAPORE

NI NE NG NU NF MP NO OM PK PW PA PG PY PE PH PN PL PT PR QA RE RO RU RW WS SM ST SA SN SC SL SG

Gateway Developer Guide and Reference

19 July 2013

233

Codes Used by FDMS South Only

Visa Country Codes

ST. HELENA ST. KITTS-NEVIS-ANGUILLA ST. LUCIA ST. PIERRE AND MIQUELON ST. VINCENT AND THE GRENADINES SUDAN SURINAME SVALBARD AND JAN MAYEN IS SWAZILAND SWEDEN SWITZERLAND SYRIAN ARAB REPUBLIC TAIWAN, PROVIDENCE OF CHINA TAJIKISTAN TANZANIA, UNITED REPUBLIC THAILAND TOGO TOKELAU TONGA TRINIDAD AND TOBAGO TUNISIA TURKEY TURKMENISTAN TURKS AND CAICOS ISLANDS TUVALU U.S. MINOR OUTLYING ISL. UGANDA UKRAINIAN SSR UNITED ARAB EMIRATES UNITED KINGDOM UNITED STATES URUGUAY

SH KN LC PM VC SD SR SJ SZ SE CH SY TW TJ TZ TH TG TK TO TT TN TR TM TC TV UM UG UA AE GB US UY

234

19 July 2013

Gateway Developer Guide and Reference

Codes Used by FDMS South Only

Units of Measure

UZBEKISTAN VANUATU VATICAN CITY STATE VENEZUELA VIETNAM VIRGIN ISLANDS BRITISH VIRGIN ISLANDS US WALLIS AND FUTUNA IS WESTERN SAHARA YEMEN YUGOSLAVIA ZAIRE ZAMBIA ZIMBABWE

UZ VU VA VE VN VG VI WF EH YE YU ZR ZM ZW

Units of Measure
Acre (4840 yd2) Alcoholic strength by mass Alcoholic strength by volume Ampere* Ampere=hour (3,6 kC)* Are (100 m2) Bar* Barrel (petroleum) (158,987 dm3) Becquerel* Billion EUR Billion US Board foot Brake horse power (245,7 watts) British thermal unit (1,055 kilojoules) ACR ASM ASV AMP AMH ARE BAR BLL BQL BIL MLD BFT BHP BTU

Gateway Developer Guide and Reference

19 July 2013

235

Codes Used by FDMS South Only

Units of Measure

Bushel (35,2391 dm3) Bushel (36,36874 dm3) Candela* Carrying capacity in metric tonnes Cental GB (45,359237 kg) Center, metric (100 kg) (syn.: Hectokilogram) Centigram* Centilitre* Centimetre* Cord (3,63 m3) Coulomb per kilogram* Coulomb* Cubic centimetre* Cubic decimetre* Cubic foot Cubic inch Cubic metre per hour* Cubic metre per second* Cubic metre* Cubic millimetre* Cubic yard Curie Day* Decade (ten years) Decare Decilitre* Decimetre* Decitonne* Degree Celsius Degree Fahrenheit Degree Kelvin: Kelvin Displacement tonnage

BUA BUI CDL CCT CNT DTN CGM CLT CMT WCD CKG COU CMQ DMQ FTQ INQ MQH MQS MTQ MMQ YDQ CUR DAY DEC DAA DLT DMT DTN CEL FAH

DPT

236

19 July 2013

Gateway Developer Guide and Reference

Codes Used by FDMS South Only

Units of Measure

Dozen Dozen packs Dozen pairs Dozen pieces Dozen rolls Drachm GB (3,887935 g) Dram GB (1,771745 g) Dram US (3,887935 g) Dry Barrel (115,627 dm3) Dry gallon (4,404884 dm3) Dry pint (0,55061 dm3) Dry quart (1,101221 dm3) Farad* Fluid ounce (28,413 cm3) Fluid ounce (29,5735 cm3) Foot (0,3048 m) Gallon (4,546092 dm3) Gigabecquerel* Gigawatt-hour (1 million kW/h)* Gill (0,142065 dm3) Gill (11,8294 cm3) Grain GB, US (64,798910 mg) Gram of fissile isotopes Gram* Great gross (12 gross) Gross Gross (register) ton Half year (six months) Hectare Hectobar* Hectogram* Hectokilogram*

DZN DZP DZR DCP DRL DRM DRI DRA BLD GLD PTD QTD FAR OZI OZA FOT GLI GBQ GWH GII GIA GRN GFI GRM GGR GRO GRT SAN HAR HBA HGM DTH

Gateway Developer Guide and Reference

19 July 2013

237

Codes Used by FDMS South Only

Units of Measure

Hectolitre of pure alcohol Hectolitre* Hectometre* Hertz* Hour* Hundred Hundred boxes Hundred international units Hundred leaves Hundred packs Hundredweight US (45,3592 kg) Inch (25,4 mm) Joule* Kelvin* Kilobar* Kilogram of caustic potash Kilogram of caustic soda Kilogram of named substance Kilogram of nitrogen Kilogram of phosphonic anhydride Kilogram of phosphorus pentoxide Kilogram of potassium hydroxide Kilogram of potassium oxide Kilogram of sodium hydroxide Kilogram of substance 90 percent dry Kilogram per cubic meter* Kilogram per second* Kilogram* Kilohertz* Kilojoule* Kilometre per hour* Kilometre*

HPA HLT HMT HTZ HUR CEN BHX HIU CLF CNP CWA INH JOU KEL KBA KPH KSH KNS KNI KPP KPP KPH KPO KSH KSD KMQ KGS KGM KHZ KJO KMH KMT

238

19 July 2013

Gateway Developer Guide and Reference

Codes Used by FDMS South Only

Units of Measure

Kilopascal* Kilorgram of uranium Kilotonne* Kilovar Kilovolt* Kilovolt-ampere* Kilowatt* Kilowatt-hour* Knot (1 nautical mile per hour) Leaf Liquid gallon (3,78541 dm3) Liquid pint (0,473176 dm3) Liquid quart (0,946353 dm3) Litre (1 dm3)* Litre of pure alcohol Long ton GB, US (1,0160469 t) (long) hundredweight GB (50,802345 kg) Lumen* Lux Megahertz* Megalitre* Megametre* Megapascal* Megavolt-ampere (1000 KVA)* Megawatt* Megawatt-hour (100 kW/h)* Metre per second squared* Metre per second* Metre* Metric carat (200 mg=2,10-4 kg) Metric ton (1000 kg) Milliard

KPA KUR KTN KVR KVT KVA KWT KWH KNT LEF GLL PTL QTL LTR LPA LTN CWI LUM LUX MHZ MAL MAM MPA MVA MAW MWH MSK MTS MTR CTM TNE MLD

Gateway Developer Guide and Reference

19 July 2013

239

Codes Used by FDMS South Only

Units of Measure

Millibar* Millicurie Milligram* Millilitre* Millimetre* Million Million cubic metres* Million international units Minute* Month Nautical mile (1852 m) Net (register) ton Newton* Number Number of articles Number of bobbons Number of cells* Number of international units Number of packs Number of pairs Number of parcels Number of parts Number of rolls Ohm* Ounce GB, US (28,349523 g) Ounce GB, US (31,103448 g) (syn: Troy ounce) Pascal* Pennyweight GB, US (1555174 g) Piece Pint (0,568262 dm3) Pound GB, US (0,45359237 kg) Proof gallon

MBR MCU MGM MLT MMT MIO HMQ MIU MIN MON NMI NTT NEW NMB NAR NBB NCL NIU NMP NMR NPL NPT NRL OHM ONZ APZ PAL DWT PCE PTI LBR PGL

240

19 July 2013

Gateway Developer Guide and Reference

Codes Used by FDMS South Only

Units of Measure

Quart (1,136523 dm3) Quarter (of a year) Quarter, GB (12,700586 kg) Quintal, metric (100 kg) Revolution per minute* Revolution per second* Score scruple, GB (1,2955982 g) Second* Set Shipping ton Short standard (7200 matches) Short ton GB, US (0,90718474 t) Siemens* Square centimetre* Square decimetre* Square foot Square inch Square kilometre* Square metre* Square mile Square millimetre* Square yard Standard standard atmosphere (101325 Pa) (statue) mile (1609,344 m) Stone GB (6,350293 kg) Technical atmosphere (98066,5 Pa) Ten days Ten pairs Thousand Thousand ampere-hour*

QTI QAN QTR DTN RPM RPS SCO SCR SEC SET SHT SST STN SIE CMK DMK FTK INK KMK MTK MIK MMK YDK WSD ATM SMI STI ATT DAD TPR MIL TAH

Gateway Developer Guide and Reference

19 July 2013

241

Codes Used by FDMS South Only

Units of Measure

Thousand board feet (2,36 m3) Thousand cubic metres per day* Thousand standard brick equivalent Ton of steam per hour Tonne (1000 kg)* Tonne of substance 90 percent dry Trillion EUR Trillion US Troy ounce Troy pound, US (373,242 g) Volt* Watt* Watt-hour* Weber Week Yard (0,9144 m) Year

MBF TQD MBE TSH TNE TSD TRL BIL APZ LBT VLT WTT WHR WEB WEE YRD ANN

242

19 July 2013

Gateway Developer Guide and Reference

Additional Processor Information

Moneris Solutions
The Moneris Solutions processor has the following characteristics: It supports ecommerce and mail order or telephone order (MOTO) transactions. It supports the four basic credit card types: American Express, Discover, MasterCard, and Visa. To process live transactions, it requires undergoing a certification process. For details, see the Moneris Receipts Specification available on the PayPal developer website.

Gateway Developer Guide and Reference

19 July 2013

243

Additional Processor Information

Moneris Solutions

244

19 July 2013

Gateway Developer Guide and Reference

Payflow Link Migration

If you are currently using the legacy Payflow Link HTML input tag integration and you would like to use the name-value pair integration, you will need to contact PayPal Merchant Technical Support to request your account to be upgraded to the new version of Payflow. Before you request an upgrade, it is important that you understand the differences between the Payflow Link legacy parameters and the equivalent Payflow parameters. Once you upgrade your account to the new version, your old legacy integration will still work. However, to take advantage of the new features we recommend that you update your Payflow Link integration and use equivalent Payflow Gateway parameters instead of the legacy Payflow Link HTML input tags.

Migrating from a legacy Payflow Link Integration

The legacy Payflow Link integration is now deprecated. It is recommended that you upgrade the version of your Payflow Link account which allows you to perform a broader set of functions. This upgrade allows you to switch from using the legacy Payflow Link HTML input tag parameters to using Payflow parameters. The table below lists legacy Payflow Link parameters and their Payflow equivalents.
Payflow Link legacy parameters and the equivalent Payflow parameters Payflow Link Legacy Parameter ADDRESS ADDRESSTOSHIP AMOUNT AVSDATA CARDNUM CITY CITYTOSHIP COUNTRY COUNTRYTOSHIP CSC CSCMATCH DESCRIPTION EMAIL Payflow Parameter BILLTOSTREET SHIPTOSTREET AMT AVSADDR and AVSZIP ACCT BILLTOCITY SHIPTOCITY BILLTOCOUNTRY SHIPTOCOUNTRY CVV2 CVV2MATCH N/A BILLTOEMAIL

Gateway Developer Guide and Reference

19 July 2013

245

Payflow Link Migration

Migrating from a legacy Payflow Link Integration

Payflow Link Legacy Parameter EMAILTOSHIP FAX FAXTOSHIP FIRSTNAME INVOICE LASTNAME LOGIN METHOD NAME

Payflow Parameter SHIPTOEMAIL BILLTOFAX SHIPTOFAX BILLTOFIRSTNAME INVNUM BILLTOLASTNAME VENDOR TENDER BILLTOFIRSTNAME BILLTOLASTNAME SHIPTOFIRSTNAME SHIPTOLASTNAME BILLTOPHONENUM SHIPTOPHONENUM FREIGHTAMT BILLTOSTATE SHIPTOSTATE TAXAMT TRXTYPE BILLTOZIP SHIPTOZIP

NAMETOSHIP

PHONE PHONETOSHIP SHIPAMOUNT STATE STATETOSHIP TAX TYPE ZIP ZIPTOSHIP

246

19 July 2013

Gateway Developer Guide and Reference

K
NOT E :

Payflow Gateway MagTek Parameters

MagTek products for both merchants and consumers provide added security to payment transactions. For merchants, MagTek's MagneSafe card readers encrypt payment card data when the card is swiped. For consumers, MagTek has a subscription based service named Qwick Codes. Consumers can use Qwick Codes instead of their payment card details to purchase goods and services. You must have a MagneSafe card reader or the required Qwick Code information to use the MagTek specific parameters described in this appendix. Please contact MagTek directly for more information.

MagTek MagneSafe Secure Card Readers and Qwick Codes Passing Encrypted Card Swipe Data and Qwick Codes to the Payflow Gateway Parameters for Encrypted Card Swipe Transactions Parameters for MagTek Qwick Code (PCode) Transactions MagTek Error Codes and Messages

MagTek MagneSafe Secure Card Readers and Qwick Codes

MagneSafe Secure Card Reader Authenticators

MagTeks MagneSafe secure card readers encrypt payment card track data such as the credit card account number and the expiration date. MagTek's Secure Card Reader Authenticators (SCRAs) capture data with a single swipe and can deliver dynamic card authentication, data encryption, tokenization, and device/host authentication to help protect merchants and their customers from identity theft and card fraud. MagTeks MagneSafe SCRAs can also identify counterfeit cards. What is MagneSafe? The MagneSafe Security Architecture (MSA) is MagTeks digital identification and authentication architecture that can safeguard consumers and their personal data. MSA leverages strong encryption, secure tokenization, counterfeit detection, tamper recognition, data relevance and integrity, and dynamic digital transaction signatures to validate and protect the entire transaction. The devices suported by MagTek's MagneSafe security and Magensa Services are:
Gateway Developer Guide and Reference 19 July 2013

247

Payflow Gateway MagTek Parameters

Passing Encrypted Card Swipe Data and Qwick Codes to the Payflow Gateway

USB MSR: Dynamag. Insert MSR for Kiosks, ATMs, etc.: MagneSafe I-65 for Chip Cards and MagStripe, PSeries MagneSafe for outdoors, Slim Seal MagneSafe. Mobile Readers: iDynamo for iOS, Bullet for Android, uDynamo for phones and tablets with audio jack port. PINPads: IPAD PINPad available as standard model and also with signature capture support.

For more information, go to: http://www.magtek.com/V2/products/secure-card-readerauthenticators/index.asp

MagTek Qwick Codes

MagTek offers a subscription based service to consumers named Qwick Codes. Instead of handing over plastic cards to store clerks or inserting them into unattended terminals like ATMs or gas pumps that may have been rigged with skimmers to steal card data, consumers can scan or type a Qwick Code from their smartphone or computer. The Qwick Code token is used instead to initiate a transaction whereby the merchant or ATM's processor can gather the actual card data on the back end of the transaction where it can be better secured and shielded from potential compromise. Qwick Code tokens are also known as Protection Codes or PCodes.

Passing Encrypted Card Swipe Data and Qwick Codes to the Payflow Gateway
The Payflow Gateway can process transactions for merchants who already have MagneSafe card readers or who accept MagTek Qwick Codes. You must have a MagneSafe card reader or the required Qwick Code information to use the MagTek specific parameters described below. Please contact MagTek directly for more information on obtaining the required card readers and codes. When you pass MagneSafe encrypted card swipe data or a Qwick Code to the Payflow Gateway, Payflow will communicate directly with MagTek's Magensa servers to retrieve the payment card information. Payflow then passes the transaction data onto your merchant bank. Supported Transaction Types Encrypted card swipe or Qwick Code (PCode) requests can be used with the following Payflow transaction types:

Authorization (TRXTYPE=A) Credit (TRXTYPE=C)

248

19 July 2013

Gateway Developer Guide and Reference

Payflow Gateway MagTek Parameters

Passing Encrypted Card Swipe Data and Qwick Codes to the Payflow Gateway

Delayed Capture (TRXTYPE=D) Sale (TRXTYPE=S) Void (TRXTYPE=V)

Encrypted Card Swipe Payflow Example

The purpose of this example is to show you how to format a request.You cannot use the values in this example for testing. You must have a MagneSafe card reader and test credit cards or live credit cards to send a request to the Payflow Gateway. Please contact MagTek for more information on obtaining card readers. Request This request contains regular Payflow parameters along with required MagTek parameters: TRXTYPE=A&TENDER=C&VENDOR=MerchantUserID&PARTNER=PayPal&USER= UserIDIfAvailOrSameAsVendor&PWD=Pwd4Gateway&VERBOSITY=HIGH&CARDTYPE= 1&SWIPEDECRHOST=MAGT&ENCTRACK2=82C69E600FF72FC1755509A76AD049E896A6E EA64D9BB2F203DF8AAD78265E90F4F8952A9AC03CFC&AMT=11.00&ENCMP=71AB2EE7 A15887C36B8A23FED1CE7E6404D98119E24D15549E9B69AB6ABFB251C4A607D6A718 B494449B506B7555BF8ED5FA4A9E2A6B814B&KSN=9011400B02AA0E00002B&MPSTAT US=3162209&ENCRYPTIONBLOCKTYPE=1&REGISTEREDBY=PayPal&MAGTEKCARDTYPE= 1&DEVICESN=B02AA0E12151 See the Encrypted Card Swipe Transactions - Request Parameters for more information. Response If successful, the response will contain the standard Payflow response parameters for your transaction type: RESULT=0&PNREF=V24A0A55E168&RESPMSG=Approved&AUTHCODE=098PNI00PN&HOS TCODE=A&VISACARDLEVEL=12 If you do not pass the required MagTek parameters, you will see: RESULT=7 in the response along with a MagTek specific error message, such as: MAGTRESPONSE=H178-ENCTRACK2 has incorrect format. See the Encrypted Card Swipe Transactions - Response Parameters for more information.

Qwick Code (PCode) Payflow Example

The purpose of this example is to show you how to format a request.You cannot use the values in this example for testing. You must have a MagTek test Qwick Code or live Qwick Codes to send a request to the Payflow Gateway. Please contact MagTek for more Qwick Code information. Request This request contains regular Payflow parameters along with required MagTek parameters:

Gateway Developer Guide and Reference

19 July 2013

249

Payflow Gateway MagTek Parameters

Parameters for Encrypted Card Swipe Transactions

TRXTYPE=A&TENDER=C&VENDOR=MerchantUserID&PARTNER=PayPal&USER=UserIDI fAvailOrSameAsVendor&PWD=Pwd4Gateway&VERBOSITY=HIGH&AMT=18&SWIPEDECR HOST=MAGT&PCODE=23456789&MERCHANTID=MerchantID123&MERCHANTNAME=Merch antName&PAN4=1234&BILLTOLASTNAME=Miller&MAGTEKUSERNAME=MagTekUserNam e&MAGTEKPWD=MagTekPwd&[email protected]&BILLT OZIP=95131&SHIPTOZIP=94089&AUTHVALUE1=1234&AUTHVALUE2=5678&AUTHVALUE 3=9012 See the Qwick Code (PCode) Transactions - Request Parameters for more information. Response If successful, the response will contain the standard Payflow response parameters for your transaction type: RESULT=0&PNREF=V24A0A55E19C&RESPMSG=Approved&AUTHCODE=474PNI00PN&HOS TCODE=A&VISACARDLEVEL=12 If you do not pass the required MagTek parameters, you will see: RESULT=7 in the response along with a MagTek specific error message, such as: MAGTRESPONSE=H364-MERCHANTID has incorrect format. See the Qwick Code (PCode) Transactions - Response Parameters for more information.

Parameters for Encrypted Card Swipe Transactions

Encrypted Card Swipe Transactions - Request Parameters Field ENCMP Required Required Description Encrypted MagnePrint Information returned by a MagneSafe device when a card is swiped. Data Type String Length

250

19 July 2013

Gateway Developer Guide and Reference

Payflow Gateway MagTek Parameters

Parameters for Encrypted Card Swipe Transactions

Field ENCRYPTIONBLOCK TYPE

Required Required

Description The code which indicates what type of Encryption Block is used. 1=MagneSafe V4/V5 compatible 2TDEA-CBC Encryption, IV=0 Block contains data only.2=iPad V1 compatible 2TDEACBC Encryption Block contains header + data. Encrypted Track 2 information returned by a MagneSafe device when a card is swiped. 20 character string returned by a MagneSafe device when a card is swiped. The code which indicates what type of Card Data Format is being submitted. 1=Encoding Format for Financial Transaction Cards (ISO 7811). MagnePrint Status of Card Swipe. This is an alpha numeric string, returned by a MagneSafe device when a card is swiped. An alpha numeric entry between 1 and 20 characters long.

Data Type Integer

Length 1

ENCTRACK2

Required

String

KSN

Required

String

20 char

MAGTEKCARDTYPE

Required

Integer

MPSTATUS

Required

REGISTEREDBY

Required

Alphanumeric [az][A-Z][0-9]

1 to 20 char

Gateway Developer Guide and Reference

19 July 2013

251

Payflow Gateway MagTek Parameters

Parameters for Encrypted Card Swipe Transactions

Field SWIPEDECRHOST

Required Required

Description MAGT is the only value that is accepted in the SWIPEDECRHOST parameter. If you pass a different value you will see RESULT=7 and MAGTRESPONSE with an error message in the response. The device serial number. Encrypted Track 1 information returned by a MagneSafe device when a card is swiped. Encrypted Track 3 information returned by a MagneSafe device when a card is swiped.

Data Type

Length

DEVICESN ENCTRACK1

Optional Optional

String String

ENCTRACK3

Optional

String

Encrypted Card Swipe Transactions - Response Parameters Field MAGTRESPONSE Description This parameter appears in the response if a data validation error occurs or if the MagTek processor throws an error. Data Type String Notes See the error codes below for more information.

252

19 July 2013

Gateway Developer Guide and Reference

Payflow Gateway MagTek Parameters

Parameters for MagTek Qwick Code (PCode) Transactions

Parameters for MagTek Qwick Code (PCode) Transactions

Qwick Code (PCode) Transactions - Request Parameters Field MERCHANTID Required Required Description Your Merchant ID or the Merchant ID of the merchant redeeming the Protection Code. The last 4 digits of the PAN / account number encoded in the card. The generated Protection Code. MAGT is the only value currently accepted in the SWIPEDECRHOST parameter. . Authentication Value 1generated with the PCode. Authentication Value 2 generated with the PCode. Authentication Value 3 generated with the PCode. Purchaser's email address. The last name of the card holder encoded in the card. The billing zipcode. MagTek username. MagTek password. String Data Type String Length 1 to 40 characters

PAN4

Required

String

4 characters

PCODE SWIPEDECRHOST

Required Required

String

8 character alphanumeric

AUTHVALUE1

Optional

AUTHVALUE2

Optional

String

AUTHVALUE3

Optional

String

BILLTOEMAIL BILLTOLASTNAME

Optional Optional

String String

BILLT0ZIP MAGTEKUSERNAME MAGTEKPWD MERCHANTNAME SHIPTOZIP

Optional Optional Optional Optional Optional

String String String

Shipping zipcode.

String

Gateway Developer Guide and Reference

19 July 2013

253

Payflow Gateway MagTek Parameters

MagTek Error Codes and Messages

Qwick Code (PCode) Transactions - Response Parameters Field MAGTRESPONSE Description This only appears in the response if a data validation error occurs or if the MagTek processor throws an error. Data Type String Notes See the error codes below for more information.

MagTek Error Codes and Messages

If an error occurs, you will see one of the following error codes in the MAGTRESPONSE response parameter.
Encrypted Card Swipe Transactions - Input Validation Error Codes Error Message H023 - REGISTEREDBY has incorrect length H024 - REGISTEREDBY has incorrect format H176 - ENCTRACK1 has incorrect format H177 - ENCTRACK1 has incorrect length H178 - ENCTRACK2 has incorrect format H179 - ENCTRACK2 has incorrect length H180 - ENCTRACK3 has incorrect format H181 - ENCTRACK3 has incorrect length H182 - ENCMP has incorrect format H183 - ENCMP has incorrect length H186 - KSN has incorrect format H187 - KSN has incorrect length H188 - MPSTATUS has incorrect format H189 - MPSTATUS has incorrect length H206 - Invalid CARDTYPE H211 - Invalid ENCRYPTIONBLOCKTYPE H219 - Invalid OUTPUTFORMATCODE H251 - Invalid DEVICESN Invalid MAGTEKCARDTYPE Notes

254

19 July 2013

Gateway Developer Guide and Reference

Payflow Gateway MagTek Parameters

MagTek Error Codes and Messages

Encrypted Card Swipe Transactions - Other Error Codes Error Message Y001 - No PAN Found in Track2 Data Y003 - Device is not allowed Y093 - Invalid MagnePrint Y094 - Invalid MagnePrint MagTek maintains a list of registered Devices. Error obtained while Scoring Transaction MagnePrint against a Reference MagnePrint made up of Zeros. Negative 2 - Invalid Transaction CRC / PAN Obtained when Scoring Transaction MagnePrint against a Reference MagnePrint Made up of Zeros. Notes

Y095 - Error Scoring Card Y096 - Inactive MagnePrint Reference Y097 - Replay Prevented Y098 - Problem with Reader Data This occurs whenever the Card has an inactive MagnePrint Reference. This occurs when the DUKPT KSN and Counter is replayed. This occurs if there is a problem while decrypting the Data..

Qwick Code (PCode) Transactions - Input Validation Error Codes Error Message H330 - PCODE has incorrect length H331 - PCODE has incorrect format H336 - EMAIL has incorrect format H337 - EMAIL has incorrect length H348 - BTZIP has incorrect format H349 - BTZIP has incorrect length H360 - STZIP has incorrect format H361 - STZIP has incorrect length H364 - MERCHANTID has incorrect format H365 - MERCHANTID has incorrect length H366 - Invalid LASTNAME H375 - PAN4 has incorrect length H376 - PAN4 has incorrect format H380 - Invalid AUTHVALUE1 Invalid BILLTOLASTNAME BILLTOEMAIL has incorrect format BILLTOEMAIL has incorrect length BILLTOZIP has incorrect format BILLTOZIP has incorrect length SHIPTOZIP has incorrect format SHIPTOZIP has incorrect length Notes

Gateway Developer Guide and Reference

19 July 2013

255

Payflow Gateway MagTek Parameters

MagTek Error Codes and Messages

Error Message H381 - Invalid AUTHVALUE2 H382 - Invalid AUTHVALUE3 H383 - Invalid MERCHANTNAME H384 - Invalid USERNAME H385 - Invalid PASSWORD

Notes

Invalid MAGTEKUSERNAME Invalid MAGTEKPWD

Qwick Code (PCode) Transactions - Other Error Codes Error Message P021 - Invalid Protection Code - Not Found. P022 - Revoked Protection Code. P028 - Expired Protection Code. P031 - Last 4 of PAN mismatch. P032 - LASTNAME mismatch. P033 - MERCHANTID is locked. P034 - Protection Code can no longer be Redeemed. P035 - USERNAME mismatch. P036 - PASSWORD mismatch. P037 - EMAIL mismatch. P038 - BTZIP mismatch. P039 - STZIP mismatch. P040 - AUTHVALUE1 mismatch. P041 - AUTHVALUE2 mismatch. P042 - AUTHVALUE3 mismatch. P098 - Problem with Reader Data MAGTEKUSERNAME given does not match the one stored. MAGTEKPWD given does not match the one stored. BILLTOEMAIL given does not match the one stored. BILLTOZIP given does not match the one stored. SHIPTOZIP given does not match the one stored. AUTHVALUE1 given does not match the one stored. AUTHVALUE2 given does not match the one stored. AUTHVALUE3 given does not match the one stored. This occurs if there is a problem while decrypting the Data. BILLTOLASTNAME mismatch. This Protection Code has already been revoked. Notes

256

19 July 2013

Gateway Developer Guide and Reference