PayPal Gateway Gateway - 2014 User 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

trademarks and brands are the property of their respective owners.

The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.

Royal, L-2449, Luxembourg, R.C.S. Luxembourg B 118 349

Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval

of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.

Notice of non-liability:

PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,

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

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

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

Gateway Developer Guide and Reference 07 January 2014 3

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

Content

4 07 January 2014 Gateway Developer Guide and Reference

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

Gateway Developer Guide and Reference 07 January 2014 5

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 Data on the Gateway Server . . . . . . . . . . . . 78

Submitting Sale Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

When To Use a Sale Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Content

6 07 January 2014 Gateway Developer Guide and Reference

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 Transaction 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 Account Updater 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

Gateway Developer Guide and Reference 07 January 2014 7

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

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

Content

8 07 January 2014 Gateway Developer Guide and Reference

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

Gateway Developer Guide and Reference 07 January 2014 9

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

Content

10 07 January 2014 Gateway Developer Guide and Reference

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

Gateway Developer Guide and Reference 07 January 2014 11

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

Content

12 07 January 2014 Gateway Developer Guide and Reference

Gateway Developer Guide and Reference 07 January 2014 13

Preface

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

Scope

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

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

resulting response data parameters and errors.

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

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

additional parameters unique to individual processors, and purchasing card parameters

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

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

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

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

integration. Refer to the

PayPal Developer website and the 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

Intended Audience

14 07 January 2014 Gateway Developer Guide and Reference

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

Payflow Link User’s 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

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

Gateway Developer Guide and Reference 07 January 2014 15

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)

Intended Audience

16 07 January 2014 Gateway Developer Guide and Reference

 PayPal Payments Advanced

Transactions submitted by PayPal Payments Advanced customers are processed through

the Gateway with PayPal acting as the merchant bank. PayPal Payments Advanced users

will see the following in the Service Summary box in PayPal Manager:

PayPal Payments Advanced with Hosted Checkout Pages & Payflow SDK/API (Limited

Access)

Limited API Access means you can perform all API functions except for Sales and

Authorization transactions. For Sales and Authorization type transactions you must use

Hosted Checkout Pages.

 PayPal Payments Pro

Transactions submitted by PayPal Payments Pro customers are processed through the

Gateway with PayPal acting as the merchant bank. PayPal Payments Pro users can use all

of the Gateway features supported by PayPal. These users will see the following in the

Service Summary box in PayPal Manager:

PayPal Payments Pro with Hosted Checkout Pages & Payflow SDK/API (Full Access)

Gateway Developer Guide and Reference 07 January 2014 17

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

Credit Card Transaction Responses;

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 (

PayPal Credit Card Transaction Request

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.

19 Jul 2013 Removed the ACCTTYPE parameter from this guide.

Revision History

18 07 January 2014 Gateway Developer Guide and Reference

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

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.

25 Apr 2013 Updated the description of the Driver’s Licencse - DL

field in

Required TeleCheck Parameters.

22 Feb 2013 Updated the description of the Driver’s Licencse - DL

field in

Required TeleCheck Parameters.

Date Description

Gateway Developer Guide and Reference 07 January 2014 19

Revision History

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.

Date Description

Revision History

20 07 January 2014 Gateway Developer Guide and Reference

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

PayPal Credit Card Transaction Request

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”

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

Date Description

Page is loading ...

PayPal Gateway Gateway - 2014 User guide

This manual is also suitable for

PayPal Gateway Gateway - 2014 User guide

Related papers

Other documents