PayPal Gateway - 2014 Developer's Guide
Gateway Developer
Guide and Reference
PayPal Payments Advanced
PayPal Payments Pro
Payflow Pro
Payflow Link
Last updated: 07 January 2014
Gateway Developer Guide and Reference
Document Number: 200045.en_US-201401
© 1999 - 2014 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other
trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
Copyright © PayPal. All rights reserved. PayPal (Europe) S.à r.l. et Cie, S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard
Royal, L-2449, Luxembourg, R.C.S. Luxembourg B 118 349
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval
of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.
Notice of non-liability:
PayPal, Inc. is providing the information i n this document t o you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information co ntained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting f rom 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. . . . . . . . 25
About the Gateway Checkout Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Summary of the Gateway Checkout Solutions . . . . . . . . . . . . . . . . . . . . . 25
Gateway Product Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
About the Gateway Transaction Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
About Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Secure Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Hosted Checkout Pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
PCI Compliance Without Hosted Pages: Transparent Redirect . . . . . . . . . . . . . 29
The PayPal Manager Website . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Processing Platforms Supporting Card-Present Transactions. . . . . . . . . . . . . . . . 30
Supported Payment Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Supported Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Recurring Billing Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Fraud Protection Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Chapter 2 Secure Token . . . . . . . . . . . . . . . . . . . . . . . .33
About the Secure Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Integrating the Secure Token With the Hosted Checkout Pages . . . . . . . . . . . . . . 34
Integrating the Secure Token Without the Hosted Checkout Pages: Transparent Redirect . 34
Secure Token Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Posting To the Hosted Checkout Page . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Chapter 3 Configuring Hosted Checkout Pages . . . . . . . . . . . . 39
Gateway Developer Guide and Reference 07 January 2014 3
Content
Configuring Hosted Checkout Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Configuring Hosted Pages Using PayPal Manager . . . . . . . . . . . . . . . . . . . . . 39
Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Customize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Integrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Using a Secure Token to Pass Hosted Pages Customization Parameters . . . . . . . . . 43
Using the PARMLIST Parameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Hosted Pages and Mobile Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Mobile Optimized Checkout Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Silent Posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Force Silent Post Confirmation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Data Returned by the Silent Post Features . . . . . . . . . . . . . . . . . . . . . . . 50
Passing Other Data to Your Server Using Post or Silent Post . . . . . . . . . . . . . . . . 50
Chapter 4 Payflow SDK. . . . . . . . . . . . . . . . . . . . . . . . . 51
Preparing the Payflow Gateway Client Application . . . . . . . . . . . . . . . . . . . . . 51
Activating Your Payflow Gateway Account. . . . . . . . . . . . . . . . . . . . . . . . . . 52
Host URL Addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Chapter 5 Sending a Simple Transaction to the Server . . . . . . . . 53
About Name-Value Pairs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Using Special Characters In Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Name-Value Parameter Syntax Guidelines . . . . . . . . . . . . . . . . . . . . . . . 54
Do Not URL Encode Name-Value Parameter Data . . . . . . . . . . . . . . . . . . . 54
Payflow Connection Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
User Parameter Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Sale Transaction Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Typical Sale Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Formatting Payflow Gateway Transactions . . . . . . . . . . . . . . . . . . . . . . . . . 56
Chapter 6 Submitting Credit Card Transactions . . . . . . . . . . . . 57
Obtaining an Internet Merchant Account. . . . . . . . . . . . . . . . . . . . . . . . . . . 58
About Credit Card Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Credit Card Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Planning Your Gateway Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Complying With E-commerce Indicator . . . . . . . . . . . . . . . . . . . . . . . . . 60
4 07 January 2014 Gateway Developer Guide and Reference
Content
Handling Credit Card Type Information . . . . . . . . . . . . . . . . . . . . . . . . . 60
Core Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Submitting Account Verifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
When To Use Account Verifications . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Required Account Verification Parameters . . . . . . . . . . . . . . . . . . . . . . . 64
Example Account Verification String. . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Submitting Authorization/Delayed Capture Transactions . . . . . . . . . . . . . . . . . . 65
When to Use Authorization/Delayed Capture Transactions . . . . . . . . . . . . . . . 65
Required Authorization Transaction Parameters . . . . . . . . . . . . . . . . . . . . 66
Submitting Balance Inquiry Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Processing Platforms Supporting Balance Inquiry Transactions . . . . . . . . . . . . 66
Required Balance Inquiry Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . 67
Example Balance Inquiry Transaction String . . . . . . . . . . . . . . . . . . . . . . 67
Submitting Card Present (SWIPE) Transactions. . . . . . . . . . . . . . . . . . . . . . . 67
Processing Platforms Supporting Card-Present Transactions. . . . . . . . . . . . . . 68
Card Present Transaction Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Submitting Credit (Refund) Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Required Credit Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . 69
Submitting Inquiry Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
When To Use an Inquiry Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Required Parameters When Using the PNREF . . . . . . . . . . . . . . . . . . . . . 71
Inquiry Transaction Parameter String Using the PNREF . . . . . . . . . . . . . . . . 72
Required Parameters When Using the CUSTREF . . . . . . . . . . . . . . . . . . . 72
Inquiry Transaction Parameter String Using the CUSTREF . . . . . . . . . . . . . . . 73
Required Parameters When Using the Secure Token. . . . . . . . . . . . . . . . . . 73
Inquiry Parameter String Using the Secure Token. . . . . . . . . . . . . . . . . . . . 73
Submitting Partial Authorizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
When To Use Partial Authorizations. . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Required Partial Authorization Parameters . . . . . . . . . . . . . . . . . . . . . . . 74
Example Partial Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Submitting Purchasing Card Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Submitting Reference Transactions (Tokenization) . . . . . . . . . . . . . . . . . . . . . 75
When To Use a Reference Transaction . . . . . . . . . . . . . . . . . . . . . . . . . 76
Transaction Types That Can Be Used As the Original Transaction . . . . . . . . . . . 76
Fields Copied From Reference Transactions . . . . . . . . . . . . . . . . . . . . . . 76
Example Reference Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Data Upload - Storing Credit Card Da ta on the Gateway Server . . . . . . . . . . . . 78
Submitting Sale Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
When To Use a Sale Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Gateway Developer Guide and Reference 07 January 2014 5
Content
Additional Parameters For Sale Transactions . . . . . . . . . . . . . . . . . . . . . . 79
Typical Sale Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . . 80
Submitting Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
About Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Ways to Send Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . 80
Submitting Voice Authorization Transactions . . . . . . . . . . . . . . . . . . . . . . . . 81
When To Use a Voice Authorization Transaction . . . . . . . . . . . . . . . . . . . . 82
Required Voice Authorization Transaction Parameters . . . . . . . . . . . . . . . . . 82
Submitting Void Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
When To Use a Void Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Required Void Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 83
Fields Copied From the Original T ransaction Into the Void Transaction. . . . . . . . . 83
Example Void Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . 84
Using Address Verification Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Example Address Verification Service Parameter String . . . . . . . . . . . . . . . . 84
Using Card Security Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Information for the PayPal Acquirer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Countries and Regions Supported by PayPal . . . . . . . . . . . . . . . . . . . . . . 86
PayPal Currency Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Chapter 7 Testing Transactions . . . . . . . . . . . . . . . . . . . .87
Setting Up The Payflow Gateway Testing Environment . . . . . . . . . . . . . . . . . . . 87
Testing Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Processors Other Than PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Credit Card Numbers for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Testing Address Verification Service. . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Testing Card Security Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Testing the Litle Automatic Acco un t Up da te r Feature . . . . . . . . . . . . . . . . . . 92
PayPal Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Credit Card Numbers for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Result Values Based On Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Chapter 8 Transaction Responses . . . . . . . . . . . . . . . . . . .97
Credit Card Transaction Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Address Verification Service Responses From PayPal . . . . . . . . . . . . . . . . . . .101
Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
Normalized Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . .103
BALAMT Response and Stored Value Cards . . . . . . . . . . . . . . . . . . . . . . . .103
6 07 January 2014 Gateway Developer Guide and Reference
Content
American Express Stored Value Card Example . . . . . . . . . . . . . . . . . . . . .103
PNREF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
RESULT Values and RESPMSG Text . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
RESULT Values For Communications Errors . . . . . . . . . . . . . . . . . . . . . . 111
Processor-specific Response Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .112
Litle Response Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
Chapter A Processors Requiring Additional Transaction Parameters 115
American Express Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . .115
Retail Transaction Advice Addendum (for SWIPE transactions) . . . . . . . . . . . .115
Internet Transaction Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Address Verification Service Parameters . . . . . . . . . . . . . . . . . . . . . . . .1 17
Location Transaction Advice Addendum Parameters . . . . . . . . . . . . . . . . . .117
Transaction Advice Detail Parameters. . . . . . . . . . . . . . . . . . . . . . . . . .119
Airline Passenger Data Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .119
American Express Other Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .120
Elavon Additional Credit Card Parameters. . . . . . . . . . . . . . . . . . . . . . . . . .121
First Data Merchant Services Nashville, Additional Credit Card Parameters . . . . . . . .122
First Data Merchant Services North, Additional Credit Card Parameters . . . . . . . . . .122
Heartland, Additional Credit Card Parameters. . . . . . . . . . . . . . . . . . . . . . . .123
Litle Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Cielo Payments, Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . .125
Paymentech Salem (New Hampshire) Additional Credit Card Parameters for American
Express . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Internet Transaction Data Parameters. . . . . . . . . . . . . . . . . . . . . . . . . .125
AVS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
Additional Credit Card Parameters for M Record . . . . . . . . . . . . . . . . . . . .127
PayPal Credit Card Transaction Request Parameters. . . . . . . . . . . . . . . . . . . .128
SecureNet Additional Credit Card Parameters for American Express . . . . . . . . . . . .133
Retail Transaction Advice Addendum (for SWIPE transactions) . . . . . . . . . . . .133
Internet Transaction Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
AVS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
Location Transaction Advice Addendum Parameters . . . . . . . . . . . . . . . . . .135
Transaction Advice Detail Parameters. . . . . . . . . . . . . . . . . . . . . . . . . .136
Airline Passenger Data Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .136
Other Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
Vantiv Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .138
Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .138
Gateway Developer Guide and Reference 07 January 2014 7
Content
Soft Merchant Descriptor Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .138
WorldPay Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . .140
Chapter B TeleCheck Electronic Check Processing . . . . . . . . . 141
TeleCheck NFTF Overview of Services . . . . . . . . . . . . . . . . . . . . . . . . . . .141
TeleCheck NFTF Processing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . .141
NFTF Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141
NFTF Processing Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
NFTF Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
TeleCheck Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144
Required TeleCheck Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Testing TeleCheck Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
Example Test Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
Preparing for TeleCheck Production Transactions. . . . . . . . . . . . . . . . . . . . . .148
Responses to TeleCheck Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . .148
Transaction Responses Common to All Tender Types . . . . . . . . . . . . . . . . .148
Response Code Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149
Sale Response Code Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149
Adjustment Code Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150
Response Codes For Status Response Packets . . . . . . . . . . . . . . . . . . . .150
TeleCheck Authorization Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . .151
Authorization – Sales Consent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
Authorization – Sales Decline/Error . . . . . . . . . . . . . . . . . . . . . . . . . . .154
Chapter C Payflow Header Parameters . . . . . . . . . . . . . . . . 155
Sending Requests Directly to PayPal Bypassing Payflow . . . . . . . . . . . . . . . . . .155
Posting Transactions Directly Without the Payflow SDK. . . . . . . . . . . . . . . . . . .156
The Payflow Message Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
Payflow Message Protocol Headers. . . . . . . . . . . . . . . . . . . . . . . . . . .157
Transaction Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
Integrator-Provided Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Chapter D Submitting Purchasing Card Level 2 and 3 Transactions . 163
About Purchasing Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163
About Program Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163
Accepted BIN Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164
About American Express Purchasing Card Transactions . . . . . . . . . . . . . . . . . .164
8 07 January 2014 Gateway Developer Guide and Reference
Content
Supported Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164
Avoiding Downgrade. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165
Submitting Successful Level 3 Transactions . . . . . . . . . . . . . . . . . . . . . .165
Edit Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165
Accepted BIN Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
American Express Purchasing Card Transaction Processing . . . . . . . . . . . . . . . .166
American Express Level 2 Parameters for American Express . . . . . . . . . . . . .166
Example American Express Level 2 Transaction Parameter String . . . . . . . . . . .169
American Express Level 3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . .169
Example American Express Level 3 Transaction Parameter String . . . . . . . . . . .171
Elavon (Formerly Nova) Purchasing Card Transaction Processing . . . . . . . . . . . . .172
Elavon Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
Elavon Additional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
Example Elavon Level 2 Transaction Parameter String . . . . . . . . . . . . . . . . .173
First Data Merchant Services (FDMS) Nashville Purchasing Card Transaction Processing.173
FDMS Nashville Commercial Card Parameters . . . . . . . . . . . . . . . . . . . . .173
First Data Merchant Services (FDMS) North Purchasing Card Transaction Processing . .174
FDMS North Purchasing Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .174
FDMS North Purchasing Card Line Item Parameters . . . . . . . . . . . . . . . . . .175
First Data Merchant Services South (FDMS) Purchasing Card Transaction Processing . .175
FDMS South Level 2 and Level 3 Purchasing Card Parameters . . . . . . . . . . . .176
FDMS South Line Item Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .177
Example FDMS South Purchasing Card Level 2 and 3 Parameter String. . . . . . . .178
Example FDMS South Line Item Parameter String . . . . . . . . . . . . . . . . . . .178
Global Payments - Central Purchasing Card Transaction Processing. . . . . . . . . . . .179
Global Payments - Central Level 2 Parameters . . . . . . . . . . . . . . . . . . . . .179
Global Payments - East Purchasing Card Transaction Processing . . . . . . . . . . . . .179
Global Payments - East Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . .179
Example Global Payments - East Level 2 Visa or MasterCard Transaction Parameter String
180
Heartland Purchasing Card Transaction Processing. . . . . . . . . . . . . . . . . . . . .180
Heartland Level 2 Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180
Heartland Level 3 MasterCard Parameters . . . . . . . . . . . . . . . . . . . . . . .181
Heartland Level 3 Visa Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .183
Litle Purchasing Card Transaction Processing. . . . . . . . . . . . . . . . . . . . . . . .186
Litle Level 2 Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186
Litle Level 3 Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187
Cielo Payments Purchasing Card Transaction Processing . . . . . . . . . . . . . . . . .189
Cielo Payments Level 2 Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . .189
Cielo Payments Level 3 MasterCard Parameters . . . . . . . . . . . . . . . . . . . .189
Gateway Developer Guide and Reference 07 January 2014 9
Content
Cielo Payments Level 3 Visa Parameters . . . . . . . . . . . . . . . . . . . . . . . .192
Paymentech Salem (New Hampshire) Purchasing Card Transaction Processing. . . . . .194
Paymentech Salem (New Hampshire) Level 2 Parameters for American Express . . .194
Paymentech Salem (New Hampshire) Level 3 Purchasing Card Parameters. . . . . .197
Paymentech Tampa Level 2 Purchasing Card Transaction Processing . . . . . . . . . . .201
Paymentech Tampa Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . .201
Example Paymentech Tampa Level 2 Visa and MasterCard Transaction Parameter String
201
Paymentech Tampa Level 3 Parameters . . . . . . . . . . . . . . . . . . . . . . . .201
Example Paymentech Tampa Level 3 Visa and MasterCard Transaction Parameter String
203
SecureNet Purchasing Card Transaction Processing . . . . . . . . . . . . . . . . . . . .204
SecureNet Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204
SecureNet Level 3 MasterCard Parameters. . . . . . . . . . . . . . . . . . . . . . .204
SecureNet Acquiring Solutions Level 3 Visa Parameters . . . . . . . . . . . . . . . .206
TSYS Acquiring Solutions Purchasing Card Transaction Processing . . . . . . . . . . . .209
TSYS Acquiring Solutions Level 2 Parameters . . . . . . . . . . . . . . . . . . . . .209
TSYS Acquiring Solutions Level 3 MasterCard Parameters. . . . . . . . . . . . . . .210
TSYS Acquiring Solutions Level 3 Visa Parameters. . . . . . . . . . . . . . . . . . .212
Vantiv Purchasing Card Transaction Processing . . . . . . . . . . . . . . . . . . . . . .215
Vantiv Purchasing Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
Vantiv Purchasing Card Line Item Parameters . . . . . . . . . . . . . . . . . . . . .216
WorldPay Purchasing Cards Transaction Processing . . . . . . . . . . . . . . . . . . . .217
WorldPay Level 2 Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
WorldPay Level 3 Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
Chapter E VERBOSITY: Processor-Specific Transaction Results . . 221
Chapter F Country Codes . . . . . . . . . . . . . . . . . . . . . . 223
Chapter G Codes Used by FDMS South Only . . . . . . . . . . . . . 225
MasterCard Country Codes for FDMS South Only . . . . . . . . . . . . . . . . . . . . .225
Visa Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
Units of Measure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239
Appendix H Additional Processor Information . . . . . . . . . . . . . 247
Moneris Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .247
10 07 January 2014 Gateway Developer Guide and Reference
Content
Chapter I Payflow Link Migration . . . . . . . . . . . . . . . . . . 249
Migrating from a legacy Payflow Link Integration . . . . . . . . . . . . . . . . . . . . . .249
Chapter J Payflow Gateway MagTek Parameters . . . . . . . . . . . 251
MagTek MagneSafe Secure Card Readers and Qwick Codes . . . . . . . . . . . . . . .251
MagneSafe Secure Card Reader Authenticators . . . . . . . . . . . . . . . . . . . .251
MagTek Qwick Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252
Passing Encrypted Card Swipe Data and Qwick Codes to the Payflow Gateway. . . . . .252
Encrypted Card Swipe Payflow Example . . . . . . . . . . . . . . . . . . . . . . . .253
Qwick Code (PCode) Payflow Example . . . . . . . . . . . . . . . . . . . . . . . . .253
Parameters for Encrypted Card Swipe Transactions . . . . . . . . . . . . . . . . . . . .254
Parameters for MagTek Qwick Code (PCode) Transactions. . . . . . . . . . . . . . . . .257
MagTek Error Codes and Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . .258
Chapter K Payflow Gateway FAQs . . . . . . . . . . . . . . . . . . 261
Gateway Developer Guide and Reference 07 January 2014 11
Content
12 07 January 2014 Gateway Developer Guide and Reference
Scope
Preface
This guide describes the data parameters for the Gateway payments solutions.
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://developer.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 07 January 2014 13
Intended Audience
Who Should Use This Document
This comprehensive developer guide includes integration information for multiple Gateway
solutions.
NOTE: Legacy Payflow Link features are not included in this guide. For legacy Payflow Link
features refer to the
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
Payflow Link User’s Guide.
If you are a legacy Payflow Link user, do not use this guide; instead, use the Payflow Link
User’s 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 07 January 2014 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 User’s 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 39.
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 07 January 2014 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 07 January 2014 Gateway Developer Guide and Reference
Revision History
Revision History
Revision History for the Gateway Developer Guide and Reference:
Date Description
07 Jan 2014 Added Paymentech Tampa Level 3 Parameters.
Updated processor name: Cielo Payments, formerly
Merchant e-Solutions.
Maintenance release.
21 Nov 2013 Updated the description of the CURRENCY field in
PayPal Credit Card Transaction Request Parameters
with information for PayPal Payments Advanced and
PayPal Payments Pro merchants.
08 Nov 2013 Added the TRANSSTATE response field description to
Credit Card Transaction Responses.
Added a note in When To Use a Sale Transaction for
PayPal Payments Advanced or PayPal Payments Pro
merchants using Fraud Protection Service (FPS).
31 Oct 2013 Submitting Account Verifications is now supported by
the PayPal processor.
Added the CCTRANSID and CCTRANS_POSDATA
response fields to
currently supported for TSYS processor only and are
useful for merchants who authorize transactions through
the Gateway but settle through a third party.
Clarified, in the Example Reference Transaction
section, that the capture step of a reference transaction
does not require the TENDER parameter.
Clarified that the duration of the Secure Token is 30
minutes.
Added a new section for Payflow Gateway FAQs.
20 Sep 2013 Updated the character limits for billing and shipping
address fields. These limits are different for the PayPal
acquirer (
Parameters) compared with all other processors (Core
Credit Card Parameters).
Provided clarification on which Country Codes to use
for each of the following: the PayPal acquirer,
TeleCheck, FDMS South, and for all other processors.
Added a section on the The PayPal Manager Website.
PayPal Credit Card Transaction Request
Credit Card Transaction Responses;
19 Jul 2013 Removed the ACCTTYPE parameter from this guide.
Gateway Developer Guide and Reference 07 January 2014 17
Revision History
Date Description
11 Jul 2013 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.
15 Jun 2013 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
Updated the support contact information for enabling
PayPal processor line-item support in the
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
Reference Transaction.section.
Updated URL paths.
Secure Token.
PayPal Credit
Example
25 Apr 2013 Updated the description of the Driver’s Licencse - DL
field in
22 Feb 2013 Updated the description of the Driver’s Licencse - DL
field in
Required TeleCheck Parameters.
Required TeleCheck Parameters.
18 07 January 2014 Gateway Developer Guide and Reference
Revision History
Date Description
28 Jan 2013 Added a new Appendix on Payflow Header Parameters.
Added information about duplicate parameters in the
Name-Value Parameter Syntax Guidelines.
In the Hosted Pages Chapter, added the Passing Other
Data to Your Server Using Post or Silent Post section,
and clarified that Silent Posts are returned for both
approved and declined transactions.
Updated the Payflow Link legacy parameters and the
equivalent Payflow parameters parameter table.
Removed legacy Payflow Link parameters with
identical Payflow equivalents.
Updated the description of the 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.
28 Dec 2012 Updated the description of the Driver’s Licencse - DL
field in
Required TeleCheck Parameters.
11 Dec 2012 Added info on forcing the Cancel URL with layout
template C to
Configuring Hosted Pages Using PayPal
Manager.
Added Secure Token error codes to Secure Token Errors
and to RESULT Values and RESPMSG Text.
04 Oct 2012 Added a new section on Hosted Pages and Mobile
Browsers and updated the Configuring Hosted
Checkout Pages chapter.
Added a new section: Supported Languages.
Added a new section: Using the PARMLIST Parameter.
Added information to the Host URL Addresses section.
29 Aug 2012 Added the Payflow Gateway MagTek Parameters
Appendix.
31 July 2012 Added a list of Setup 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.
Gateway Developer Guide and Reference 07 January 2014 19
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 Added the Bill Me Later feature to the Gateway Product
Details section.
16 July 2012 Updated the value of the required column for the
BILLTOCITY, BILLTOSTATE & BILLTOCOUNTRY
parameters in
Parameterstable.
June 2012 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”
PayPal Credit Card Transaction Request
Added Silent Posts section to the Hosted Checkout
Pages chapter.
Removed the legacy paramater CORPCOUNTRYfrom
Country Codes.
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
20 07 January 2014 Gateway Developer Guide and Reference
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 processor’s 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
Revision History
January 2012 Added new processors:
First Third International
Heartland Payment Systems
Planet Payment
SecureNet
TeleCheck
World Pa y
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.
Gateway Developer Guide and Reference 07 January 2014 21
Revision History
Date Description
January 2012 (cont.) 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)
22 07 January 2014 Gateway Developer Guide and Reference
Date Description
January 2012 (cont.) Added concepts:
Gateway Product Solutions - PayPal Payments
Advanced, PayPal Payments Pr o, Payflow Pro, Payflow
Link
Transaction Flow
Transparent Redirect
February 2011 First publication.
Revision History
Gateway Developer Guide and Reference 07 January 2014 23
Revision History
24 07 January 2014 Gateway Developer Guide and Reference
Introducing the Gateway
1
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 25
“About the Gateway Transaction Flow” on page 27
“About Security” on page 28
“Processing Platforms Supporting Card-Present Transactions” on page 30
“Supported Payment Types” on page 31
“Recurring Billing Service” on page 32
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 07 January 2014 25
Introducing the Gateway Checkout Solutions
1
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.
NOTE: PayPal strongly recommends that all users of Gateway checkout solutions take
advantage of the secure token and the hosted checkout pages. Doing so provides
automatic compliance with processing card industry (PCI) standards for protecting
cardholder data.
Gateway Product Details
The table below compares how the Gateway checkout solutions support payment processing
features.
PayPal Payments Advanced
Feature
Hosted checkout page (including an
iFrame version)
PayPal payments Included Optional
Bill Me Later payments
(Available to US merchants only on
Hosted checkout pages.)
PayPal branding on full page templates Ye s Optional
Transparent Redirect No Ye s
Supports PayPal as a processor and an
acquirer
Credit and debit cards Ye s Ye s
Level 2 and Level 3 purchase cards Ye s Ye s
TeleCheck (guaranteed electronic
checks)
ACH (electronic checks) No Ye s
Virtual Terminal support, including
card-present data passage
Payflow Link
Ye s Ye s
Included Optional
Ye s Ye s
No Ye s
Ye s Ye s
PayPal Payments Pro
Payflow Pro
Virtual Terminal Payflow Link only Ye s
API Limited access (Authorization and
Sale API calls not permitted)
26 07 January 2014 Gateway Developer Guide and Reference
Full access
Introducing the Gateway Checkout Solutions
About the Gateway Transaction Flow
1
PayPal Payments Advanced
Feature
Reference transactions (Tokenization) Ye s Ye s
Secure token to preset hosted checkout
page
Reporting APIs Ye s Ye s
Desktop integration Ye s Ye s
Recurring billing Ye s Ye s
Basic fraud protection Ye s Ye s
Advanced fraud protection Ye s Ye s
Partner/channel distribution support
(Partner Manager, registration, XML
registration) resale and referral
Payflow Link
Ye s Ye s
Ye s Ye s
About the Gateway Transaction Flow
PayPal Payments Pro
Payflow Pro
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 07 January 2014 27
Introducing the Gateway Checkout Solutions
1
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.
NOTE: PayPal Payments Advanced and Payflow Link merchants are required to use hosted
pages.
Secure Token
The secure token stores request transaction data on the Gateway server. It eliminates the need
to resend the parameter data for display in a hosted checkout page where the data might be
subject to compromise.
Hosted Checkout Pages
The Gateway enables the use of hosted checkout pages, which help you achieve PCI
compliance. The hosted checkout pages enable you to pass transaction data securely to the
server and to collect credit card acceptance data.
NOTE: You are required to use hosted pages with PayPal Payments Advanced and Payflow
Link.
The following figure shows the transaction flow when using hosted pages and a secure token.
28 07 January 2014 Gateway Developer Guide and Reference
Introducing the Gateway Checkout Solutions
Numbers in the figure correspond to the numbered comments below:
About Security
1
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.
NOTE: If you do not get a response from the Gateway server, submit an Inquiry transaction,
passing in the secure token to see if the transaction has completed. For details, see
“Submitting Inquiry Transactions” on page 71.
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 07 January 2014 29
Introducing the Gateway Checkout Solutions
1
The PayPal Manager Website
Implementing Transparent Redirect is very similar to implementing hosted pages. It differs
only in the steps shown in boldface below:
1. The customer clicks Buy to purchase merchandise on your website.
2. You request a secure token by passing a secure token ID to the Gateway server. In the
request, you pass the name-value pair, SILENTTRAN=TRUE. This name-value pair
prevents the hosted pages from displaying.
3. The Gateway server returns the secure token and your token ID to your website.
4. You display the credit card fields to the customer in a checkout page on your website.
5. The customer enters their credit card number, expiration date, and other sensitive
data into the credit card fields and clicks Submit. The browser posts the payment data
directly to the Gateway server, avoiding your website and easing your PCI
compliance requirements.
NOTE: To ensure that the post goes from the browser directly to PayPal and not back to
your website, you should add scripting.
6. The Gateway processes the payment through the payment processing network.
7. The Gateway server transparently sends the customer to the location on your website that
you specified in the request to obtain a secure token. You display the results to the customer
on your website.
The PayPal Manager Website
Payflow merchants can manage their Payflow account settings, view reports, and perform
transactional processing on the Payflow Manager website:
https://manager.paypal.com/.
For assistance with using the Payflow Manager website, refer to the website’s online help.
NOTE: PayPal Payments Advanced and PayPal Payments Pro merchants should also use the
Payflow Manager website (
https://manager.paypal.com/) to perform transactional
processing functions instead of the the main paypal.com website. However, the main
paypal.com website can be used to process chargebacks or other non-transactional
items.
Processing Platforms Supporting Card-Present Transactions
The following processing platforms support card-present transactions.
For instructions on setting up or changing your processor, see the
NOTE: PayPal Australia (FDRA) merchants with a 12-digit merchant ID, can contact Payflow
support to request a 16-digit merchant ID.
30 07 January 2014 Gateway Developer Guide and Reference
Processor Setup Guide (PDF).
Loading...