PayPal Gateway - 2013 Developer's Guide

Download

Gateway Developer Guide and Reference

PayPal Payments Advanced PayPal Payments Pro Payflow Pro Payflow Link

Last updated: 07 February 2013

Gateway Developer Guide and Reference

Document Number: 200045.en_US-201302

© 2013 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners. The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc. Copyright © PayPal. All rights reserved. PayPal (Europe) S.à r.l. et Cie., S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L-2449, Luxembourg, R.C.S. Luxembourg B 118 349. Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.

Notice of non-liability: PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express, implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.

Content

Chapter Preface . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Who Should Use This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

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

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

Summary of the Gateway Checkout Solutions . . . . . . . . . . . . . . . . . . . . . 23

Gateway Product Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

About the Gateway Transaction Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

About Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Secure Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Hosted Checkout Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

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

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

Supported Payment Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Supported Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Recurring Billing Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Fraud Protection Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Chapter 2 Secure Token . . . . . . . . . . . . . . . . . . . . . . . .31

About the Secure Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

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

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

Secure Token Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Posting To the Hosted Checkout Page . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Chapter 3 Configuring Hosted Checkout Pages . . . . . . . . . . . .37

Configuring Hosted Checkout Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Gateway Developer Guide and Reference 07 February 2013 3

Content

Configuring Hosted Pages Using PayPal Manager . . . . . . . . . . . . . . . . . . . . . 37

Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Customize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Integrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Using a Secure Token to Pass Hosted Pages Customization Parameters . . . . . . . . . 41

Using the PARMLIST Parameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Hosted Pages and Mobile Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Mobile Optimized Checkout Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Silent Posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Force Silent Post Confirmation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

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

Passing Other Data to Your Server Using Post or Silent Post . . . . . . . . . . . . . . . . 48

Chapter 4 Payflow SDK . . . . . . . . . . . . . . . . . . . . . . . . .49

Preparing the Payflow Gateway Client Application . . . . . . . . . . . . . . . . . . . . . 49

Activating Your Payflow Gateway Account. . . . . . . . . . . . . . . . . . . . . . . . . . 50

Host URL Addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

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

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

Using Special Characters In Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Name-Value Parameter Syntax Guidelines . . . . . . . . . . . . . . . . . . . . . . . 52

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

Payflow Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

User Parameter Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Sale Transaction Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Typical Sale Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Formatting Payflow Gateway Transactions . . . . . . . . . . . . . . . . . . . . . . . . . 54

Chapter 6 Submitting Credit Card Transactions . . . . . . . . . . . .55

Obtaining an Internet Merchant Account . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

About Credit Card Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Credit Card Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Planning Your Gateway Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Complying With E-commerce Indicator . . . . . . . . . . . . . . . . . . . . . . . . . 58

Handling Credit Card Type Information . . . . . . . . . . . . . . . . . . . . . . . . . 58

4 07 February 2013 Gateway Developer Guide and Reference

Content

Core Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Submitting Account Verifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

When To Use Account Verifications . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Required Account Verification Parameters . . . . . . . . . . . . . . . . . . . . . . . 62

Example Account Verification String . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Submitting Authorization/Delayed Capture Transactions . . . . . . . . . . . . . . . . . . 63

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

Required Authorization Transaction Parameters . . . . . . . . . . . . . . . . . . . . 64

Typical Authorization Transaction Parameter String . . . . . . . . . . . . . . . . . . . 64

Submitting Balance Inquiry Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Processing Platforms Supporting Balance Inquiry Transactions . . . . . . . . . . . . 65

Required Balance Inquiry Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Example Balance Inquiry Transaction String . . . . . . . . . . . . . . . . . . . . . . 65

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

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

Card Present Transaction Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Submitting Credit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Required Credit Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . 67

Submitting Inquiry Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

When To Use an Inquiry Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Required Parameters When Using the PNREF . . . . . . . . . . . . . . . . . . . . . 70

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

Required Parameters When Using the CUSTREF . . . . . . . . . . . . . . . . . . . 70

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

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

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

Submitting Partial Authorizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

When To Use Partial Authorizations . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Required Partial Authorization Parameters . . . . . . . . . . . . . . . . . . . . . . . 72

Example Partial Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Submitting Purchasing Card Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Submitting Reference Transactions (Tokenization) . . . . . . . . . . . . . . . . . . . . . 74

When To Use a Reference Transaction . . . . . . . . . . . . . . . . . . . . . . . . . 74

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

Fields Copied From Reference Transactions . . . . . . . . . . . . . . . . . . . . . . 75

Example Reference Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

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

Submitting Sale Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

When To Use a Sale Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Gateway Developer Guide and Reference 07 February 2013 5

Content

Additional Parameters For Sale Transactions . . . . . . . . . . . . . . . . . . . . . . 77

Typical Sale Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . . 78

Submitting Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

About Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Ways to Send Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . 79

Submitting Voice Authorization Transactions . . . . . . . . . . . . . . . . . . . . . . . . 80

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

Required Voice Authorization Transaction Parameters . . . . . . . . . . . . . . . . . 80

Submitting Void Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

When To Use a Void Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Required Void Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 81

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

Example Void Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . 82

Using Address Verification Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Example Address Verification Service Parameter String . . . . . . . . . . . . . . . . 82

Using Card Security Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Chapter 7 Testing Transactions . . . . . . . . . . . . . . . . . . . . 85

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

Testing Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Processors Other Than PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Credit Card Numbers for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Testing Address Verification Service. . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Testing Card Security Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

PayPal Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Credit Card Numbers for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Result Values Based On Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Chapter 8 Transaction Responses . . . . . . . . . . . . . . . . . . .95

Credit Card Transaction Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Address Verification Service Responses From PayPal . . . . . . . . . . . . . . . . . . . 98

Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100

Normalized Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . .100

PayPal Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . . . .100

BALAMT Response and Stored Value Cards . . . . . . . . . . . . . . . . . . . . . . . .101

American Express Stored Value Card Example . . . . . . . . . . . . . . . . . . . . .101

PNREF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

6 07 February 2013 Gateway Developer Guide and Reference

Content

RESULT Values and RESPMSG Text . . . . . . . . . . . . . . . . . . . . . . . . . . . .102

RESULT Values For Communications Errors . . . . . . . . . . . . . . . . . . . . . .108

Chapter A Processors Requiring Additional Transaction Parameters 111

American Express Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . 111

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

Internet Transaction Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112

Address Verification Service Parameters . . . . . . . . . . . . . . . . . . . . . . . .113

Location Transaction Advice Addendum Parameters . . . . . . . . . . . . . . . . . . 113

Transaction Advice Detail Parameters. . . . . . . . . . . . . . . . . . . . . . . . . .115

Airline Passenger Data Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .115

American Express Other Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Elavon Additional Credit Card Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . 117

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

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

Heartland, Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . 119

Litle Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

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

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

Express . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121

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

AVS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122

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

PayPal Credit Card Transaction Request Parameters. . . . . . . . . . . . . . . . . . . .123

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

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

Internet Transaction Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129

AVS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129

Location Transaction Advice Addendum Parameters . . . . . . . . . . . . . . . . . .130

Transaction Advice Detail Parameters. . . . . . . . . . . . . . . . . . . . . . . . . .131

Airline Passenger Data Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .131

Other Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133

Vantiv Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .133

Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .133

Soft Merchant Descriptor Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .134

WorldPay Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . .135

Chapter B TeleCheck Electronic Check Processing . . . . . . . . . 137

Gateway Developer Guide and Reference 07 February 2013 7

Content

TeleCheck NFTF Overview of Services . . . . . . . . . . . . . . . . . . . . . . . . . . .137

TeleCheck NFTF Processing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . .137

NFTF Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137

NFTF Processing Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . .139

NFTF Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139

TeleCheck Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140

Required TeleCheck Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .141

Testing TeleCheck Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143

Example Test Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143

Preparing for TeleCheck Production Transactions . . . . . . . . . . . . . . . . . . . . . .144

Responses to TeleCheck Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . .144

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

Response Code Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145

Sale Response Code Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145

Adjustment Code Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

Response Codes For Status Response Packets . . . . . . . . . . . . . . . . . . . .146

TeleCheck Authorization Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . .147

Authorization – Sales Consent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147

Authorization – Sales Decline/Error . . . . . . . . . . . . . . . . . . . . . . . . . . .150

Chapter C Submitting Purchasing Card Level 2 and 3 Transactions . 151

About Purchasing Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151

About Program Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151

Accepted BIN Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152

About American Express Purchasing Card Transactions . . . . . . . . . . . . . . . . . .152

Supported Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152

Avoiding Downgrade. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153

Submitting Successful Level 3 Transactions . . . . . . . . . . . . . . . . . . . . . .153

Edit Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153

Accepted BIN Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154

American Express Purchasing Card Transaction Processing . . . . . . . . . . . . . . . .154

American Express Level 2 Parameters for American Express . . . . . . . . . . . . .154

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

American Express Level 3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . .157

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

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

Elavon Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160

Elavon Additional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160

8 07 February 2013 Gateway Developer Guide and Reference

Content

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

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

FDMS Nashville Commercial Card Parameters . . . . . . . . . . . . . . . . . . . . .161

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

FDMS North Purchasing Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .162

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

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

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

FDMS South Line Item Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .165

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

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

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

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

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

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

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

Heartland Purchasing Card Transaction Processing. . . . . . . . . . . . . . . . . . . . .168

Heartland Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168

Heartland Level 3 MasterCard Parameters . . . . . . . . . . . . . . . . . . . . . . .169

Heartland Level 3 Visa Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .171

Litle Purchasing Card Transaction Processing. . . . . . . . . . . . . . . . . . . . . . . .174

Litle Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .174

Litle Level 3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175

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

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

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

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

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

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

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

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

Paymentech Tampa Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . .189

Example Paymentech Tampa Level 2 Visa and MasterCard Transaction Parameter String 189

SecureNet Purchasing Card Transaction Processing . . . . . . . . . . . . . . . . . . . .189

SecureNet Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189

SecureNet Level 3 MasterCard Parameters . . . . . . . . . . . . . . . . . . . . . . .190

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

Gateway Developer Guide and Reference 07 February 2013 9

Content

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

TSYS Acquiring Solutions Level 2 Parameters . . . . . . . . . . . . . . . . . . . . .195

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

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

Vantiv Purchasing Card Transaction Processing . . . . . . . . . . . . . . . . . . . . . .201

Vantiv Purchasing Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201

Vantiv Purchasing Card Line Item Parameters . . . . . . . . . . . . . . . . . . . . .201

WorldPay Purchasing Cards Transaction Processing . . . . . . . . . . . . . . . . . . . .202

WorldPay Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .202

WorldPay Level 3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204

Chapter D Payflow Header Parameters . . . . . . . . . . . . . . . . 207

Sending Requests Directly to PayPal Bypassing Payflow . . . . . . . . . . . . . . . . . .207

Posting Transactions Directly Without the Payflow SDK. . . . . . . . . . . . . . . . . . .208

The Payflow Message Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . .208

Payflow Message Protocol Headers . . . . . . . . . . . . . . . . . . . . . . . . . . .209

Transaction Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Integrator-Provided Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212

Chapter E VERBOSITY: Processor-Specific Transaction Results . . 215

Chapter F ISO Country Codes . . . . . . . . . . . . . . . . . . . . 217

Chapter G Codes Used by FDMS South Only . . . . . . . . . . . . . 219

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

Visa Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226

Units of Measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233

Chapter H PayPal Acquirer . . . . . . . . . . . . . . . . . . . . . . 241

Countries and Regions Supported by PayPal . . . . . . . . . . . . . . . . . . . . . . . .241

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241

PayPal Currency Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241

Appendix I Additional Processor Information . . . . . . . . . . . . . 243

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

10 07 February 2013 Gateway Developer Guide and Reference

Content

Chapter J Payflow Link Migration . . . . . . . . . . . . . . . . . . 245

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

Chapter K Payflow Gateway MagTek Parameters . . . . . . . . . . . 247

MagTek MagneSafe Secure Card Readers and Qwick Codes . . . . . . . . . . . . . . .247

MagneSafe Secure Card Reader Authenticators . . . . . . . . . . . . . . . . . . . .247

MagTek Qwick Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248

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

Encrypted Card Swipe Payflow Example . . . . . . . . . . . . . . . . . . . . . . . .249

Qwick Code (PCode) Payflow Example . . . . . . . . . . . . . . . . . . . . . . . . .249

Parameters for Encrypted Card Swipe Transactions . . . . . . . . . . . . . . . . . . . .250

Parameters for MagTek Qwick Code (PCode) Transactions. . . . . . . . . . . . . . . . .253

MagTek Error Codes and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254

Gateway Developer Guide and Reference 07 February 2013 11

Content

12 07 February 2013 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 Payflow Gateway SDK for detailed

working examples and use cases.

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 February 2013 13

Preface

Intended Audience

Who Should Use This Document

This comprehensive developer guide includes integration information for multiple Gateway solutions. Legacy Payflow Link features are not included in this guide. For legacy Payflow Link features refer to the 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. Additionally, all the Gateway features

If you are a legacy Payflow Link user, do not use this guide; instead, use the

User’s Guide.

Payflow Link

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 February 2013 Gateway Developer Guide and Reference

Preface

Intended Audience

New Payflow Link users who are using the Secure Token or the API should use this guide. However, new Payflow Link users who are using the legacy Payflow Link input tag integration should use the

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 Link User’s Guide instead.

Payflow Pro customers can choose PayPal or another merchant bank to process their transactions via the Gateway.

A) Legacy Payflow Pro users will see the following in the Service Summary box in PayPal Manager:

Payflow Pro

Legacy Payflow Pro users should use this guide; however, these users can only use the API integration and do not have the Hosted Checkout Pages service. If you are a legacy Payflow Pro user, you should skip the chapter on Hosted Checkout Pages - “Configuring

Hosted Checkout Pages” on page 37.

B) New Payflow Pro users can take advantage of all of the Gateway features including Hosted Checkout Pages. These users will see the following in the Service Summary box in PayPal Manager:

Hosted Checkout Pages & Payflow SDK/API (Full Access)

Gateway Developer Guide and Reference 07 February 2013 15

Preface

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 February 2013 Gateway Developer Guide and Reference

Preface

Revision History

Revision History for the Gateway Developer Guide and Reference:

Date Description

28 Jan 2013 Added a new Appendix on Payflow Header Parameters.

Added information about duplicate parameters in the

Name-Value Parameter Syntax Guidelines.

In the Hosted Pages Chapter, added the Passing Other

Data to Your Server Using Post or Silent Post section,

and clarified that Silent Posts are returned for both approved and declined transactions.

Updated the Payflow Link legacy parameters and the

equivalent Payflow parameters parameter table.

Removed legacy Payflow Link parameters with identical Payflow equivalents.

Updated the description of the BILLTOSTATE and SHIPTOSTATE parameters in the Core Credit Card

Parameters table.

Added a note to the introduction of the Submitting

Credit Card Transactions chapter.

Revised the introduction to the Payflow SDK chapter. Updated some of the external links in the guide. Corrected the format of the ORDERDATE parameter in

TSYS Acquiring Solutions Level 3 Visa Extended Data.

28 Dec 2012 Updated the description of the 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 Params and Customize Params.

These parameters override PayPal Manager settings for Hosted Pages.

Gateway Developer Guide and Reference 07 February 2013 17

Preface

Revision History

Date Description

Briefly explained the differences between Submitting

Credit Transactions and Submitting Void Transactions.

Updated the parameters in the Payflow Link legacy

parameters and the equivalent Payflow parameters

table.

Added DATE_TO_SETTLE to Credit Card Transaction

Responses parameters table.

Added a note to the About Credit Card Processing section.

23 July 2012 Added the Bill Me Later feature to the Gateway Product

Details section.

16 July 2012 Updated required value for BILLTOCITY,

BILLTOSTATE & BILLTOCOUNTRY in PayPal Credit

Card Transaction Request Parameters table.

June 2012 Who Should Use This Document section added to the

Preface.

Integrating the Secure Token Without the Hosted Checkout Pages: Transparent Redirect section:

corrected value of SILENTTRAN to “True”

Silent Posts section added to Hosted Checkout Pages

chapter.

ISO Country Codes: removed the legacy paramater

CORPCOUNTRY

May 2012 Added new sections to the Testing Transactions

chapter:

Testing Address Verification ServiceTesting Card Security Code

Added PayPal Acquirer chapter:

Contains links to PayPal API Ref country and currency codes

May 2012 (cont.) Document maintenance: Added cross-references and

external links; reorganized content; removed no longer applicable content.

April 2012 Added new transaction type:

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

18 07 February 2013 Gateway Developer Guide and Reference

Date Description

Updated TeleCheck chapter:

Updated MICR values in Testing TeleCheck Transactions section

Added TeleCheck Adjustment Response Code Values table

Updated parameters and examples:

Added a description for response parameters HOSTCODE, RESPTEXT, PROCCARDSECURE, ADDLMSGS and an explanation on how to use these

parameters to obtain the processor’s raw response codes and response messages.

Changed Litle parameters from STREET2,STREET3 to

BILLTOSTREET2, BILLTOSTREET3

Corrected description of MERCHSVC parameter for FDMS North, Heartland, Litle, Merchant e-Solutions, Paymentech Salem

Updated examples and removed legacy parameters to include:FIRSTNAME, LASTNAME, STREET, CITY, STATE, ZIP, COUNTRY

Preface

Revision History

Updated processor and entity names:

Vantiv, previously known as Fifth Third Processing Solutions

PayPal Australia, previously known as First Data Australia

January 2012 Added new processors:

First Third International Heartland Payment Systems Planet Payment SecureNet TeleCheck 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 February 2013 19

Preface

Revision History

Date Description

January 2012 (cont.) Added request NVPs:

ADDLAMT ADDLAMTTYPEn AUTHDATE CATTYPE CONTACTLESS CUSTDATA CUSTOMERID CUSTOMERNUMBER DISCOUNT DUTYAMT DLNAME DLNUM DOB L_ALTTAXAMT L_ALTTAXIDn L_ALTTAXRATEn L_CARRIERSERVICELEVELCODEn L_COMMCODEn L_EXTAMTn L_PRODCODEn L_TAXTYPEn ORDERID MERCHANTDESCR MERCHANTINVNUM MERCHANTNAME MERCHANTURL MERCHANTVATNUM MERCHANTZIP MISCDATA REPORTGROUP SILENTTRAN STREET3 VATINVNUM VATTAXAMT VATTAXRATE

Added response NVPs:

DUPLICATE (response) EXTRMSG (response)

20 07 February 2013 Gateway Developer Guide and Reference

Date Description

January 2012 (cont.) Added concepts:

Gateway Product Solutions - PayPal Payments Advanced, PayPal Payments Pro, Payflow Pro, Payflow Link

Transaction Flow Transparent Redirect

February 2011 First publication.

Preface

Revision History

Gateway Developer Guide and Reference 07 February 2013 21

Preface

Revision History

22 07 February 2013 Gateway Developer Guide and Reference

Introducing the Gateway

Checkout Solutions

The Gateway provides checkout solutions for novice and advanced use. It provides merchants with a rich set of options to handle payment transactions.

 “About the Gateway Checkout Solutions” on page 23

 “About the Gateway Transaction Flow” on page 25

 “About Security” on page 26

 “Processing Platforms Supporting Card-Present Transactions” on page 28

 “Supported Payment Types” on page 29

 “Recurring Billing Service” on page 30

About the Gateway Checkout Solutions

Gateway checkout consists of the following four solutions:

 Payflow Link

 Payflow Pro

 PayPal Payments Advanced

 PayPal Payments Pro

Summary of the Gateway Checkout Solutions

Below is a basic comparison of the Gateway checkout solutions:

 Payflow Link uses hosted checkout pages to send transactions to a supported processor.

Merchants can use the Payflow SDK APIs to perform all transactions except authorization and sale transactions. By using hosted pages with a secure token, the merchant adheres to compliance rules for handling customer data in a secure way: data is stored on PayPal so that it is not exposed to compromise.

 Payflow Pro can send transactions to a number of different supported processors,

requirements for which are described in this documentation. Merchants select a supported processor and obtain an acquiring bank. Typically merchants integrate with, and have full access to, the Payflow SDK or use HTTPS to send transactions to the processor. Using hosted pages is an option.

 PayPal Payments Advanced uses web pages hosted by PayPal (also known as hosted

checkout pages) to send transactions to the PayPal processor. With PayPal Payments

Advanced, PayPal is the acquiring bank. By using hosted checkout pages with a secure

Gateway Developer Guide and Reference 07 February 2013 23

Introducing the Gateway Checkout Solutions

About the Gateway Checkout Solutions

token, the merchant adheres to compliance rules for handling customer data in a secure way: data is stored on PayPal so that it is not exposed to compromise.

 Like PayPal Payments Advanced, PayPal Payments Pro sends transactions to the PayPal

processor and PayPal is the acquiring bank. Using hosted checkout pages is an option. Typically merchants integrate with the Payflow SDK or use HTTPS to send transactions to the PayPal processor.

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 Yes Optional

Transparent Redirect No Yes

Supports PayPal as a processor and an acquirer

Credit and debit cards Yes Yes

Level 2 and Level 3 purchase cards Yes Yes

TeleCheck (guaranteed electronic checks)

ACH (electronic checks) No Yes

Virtual Terminal support, including card-present data passage

Payflow Link

Ye s Ye s

Included Optional

Ye s Ye s

No Yes

Ye s Ye s

PayPal Payments Pro Payflow Pro

Virtual Terminal Payflow Link only Yes

API Limited access (no authorization

or sale)

24 07 February 2013 Gateway Developer Guide and Reference

Full access

Introducing the Gateway Checkout Solutions

About the Gateway Transaction Flow

PayPal Payments Advanced

Feature

Reference transactions (Tokenization) Yes Yes

Secure token to preset hosted checkout page

Reporting APIs Yes Yes

Desktop integration Yes Yes

Recurring billing Yes Yes

Basic fraud protection Yes Yes

Advanced fraud protection Yes Yes

Partner/channel distribution support (Partner Manager, registration, XML registration) resale and referral

Payflow Link

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 February 2013 25

Introducing the Gateway Checkout Solutions

About Security

 Each Gateway processor may support various additional parameters beyond the core set

that you can send in transaction requests.

 Your processor may also support purchasing cards (credit cards employers issue for

business-related charges). Purchasing card Level 2 and Level 3 parameters provide specialized reporting so an employer can monitor card use. The parameter information may appear on the customer’s statement or describe line items in greater detail. Be sure to check for your processor’s Level 2 and 3 parameters in this documentation.

The sections in this documentation describing the above parameters alphabetically organize parameters by processor name.

About Security

It is your responsibility to adhere to PCI compliance standards to protect personal information and implement security safeguards on your website when processing payment card transactions.

Gateway solutions make available a secure token and hosted checkout pages to help you meet PCI compliance. Hosted pages are optional to PayPal Payments Pro and Payflow Pro users. If you do not use a secure token or hosted pages, you must provide your own means of meeting compliance requirements.

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.

26 07 February 2013 Gateway Developer Guide and Reference

Introducing the Gateway Checkout Solutions

Numbers in the figure correspond to the numbered comments below:

About Security

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

PCI Compliance Without Hosted Pages: Transparent Redirect

PayPal Payments Pro and Payflow Pro merchants who want PCI compliance while maintaining full control over designing and hosting checkout pages on their website can use Transparent Redirect. Transparent Redirect posts payment details silently to the Gateway server, so this sensitive information never goes through the merchant’s website.

Gateway Developer Guide and Reference 07 February 2013 27

Introducing the Gateway Checkout Solutions

Processing Platforms Supporting Card-Present Transactions

Implementing Transparent Redirect is very similar to implementing hosted pages. It differs only in the steps shown in boldface below:

1. The customer clicks Buy to purchase merchandise on your website.

2. You request a secure token by passing a secure token ID to the Gateway server. In the request, you pass the name-value pair, SILENTTRAN=TRUE. This name-value pair prevents the hosted pages from displaying.

3. The Gateway server returns the secure token and your token ID to your website.

4. You display the credit card fields to the customer in a checkout page on your website.

5. The customer enters their credit card number, expiration date, and other sensitive data into the credit card fields and clicks Submit. The browser posts the payment data directly to the Gateway server, avoiding your website and easing your PCI compliance requirements.

NOTE: To ensure that the post goes from the browser directly to PayPal and not back to

your website, you should add scripting.

6. The Gateway processes the payment through the payment processing network.

7. The Gateway server transparently sends the customer to the location on your website that

you specified in the request to obtain a secure token. You display the results to the customer on your website.

Processing Platforms Supporting Card-Present Transactions

The following processing platforms support card-present transactions.

American Express

American Express APAC

Elavon

First Data Merchant Services (FDMS) Nashville

First Data Merchant Services (FDMS) North

First Data Merchant Services (FDMS) South

Global Payments Central

Global Payments East

Heartland Payment Systems

Litle

Merchant e-Solutions

28 07 February 2013 Gateway Developer Guide and Reference

Moneris Solutions

Paymentech Salem

Paymentech Tampa

PayPal

SecureNet

TeleCheck

TSYS Acquiring Solutions

Va nt iv

World Pa y

Supported Payment Types

Introducing the Gateway Checkout Solutions

Supported Payment Types

Credit cards

PayPal (supported by PayPal’s Express Checkout product)

Pinless debit cards

Electronic checks

Check cards

Purchasing cards (also referred to as commercial cards, corporate cards, procurement cards, or business cards) Level 2 and Level 3

Automated Clearing House (ACH). For information on performing ACH transactions, contact your PayPal Sales Representative.

Supported Languages

The Payflow Gateway only supports customer input and API parameter values that are in regular ASCII (English language) characters. Payflow does not support extended ASCII characters or any other character sets other than regular ASCII at this time. Additionally, the Payflow hosted checkout pages and PayPal manager account settings pages are available in English only. For information on a similar PayPal product that offers multi-lingual support, see

Website Payments Pro Hosted Solution.

Gateway Developer Guide and Reference 07 February 2013 29

Introducing the Gateway Checkout Solutions

Recurring Billing Service

The Recurring Billing Service is a scheduled payment solution that enables you to automatically bill your customers at regular intervals—for example, you can bill your customers a monthly fee of $42 for 36 months with an initial fee of $129.

You enroll separately for the Recurring Billing Service. You can learn about the Recurring Billing Service in the this service, this user guide will show you how to define and manage recurring transactions programmatically. You can also manage Recurring Billing tasks in

Payflow Pro – Recurring Billing Service User’s Guide. If you already have

Fraud Protection Service

Fraud Protection Services can help you significantly reduce the cost of fraud and the resulting damage to your business. This service uses Fraud Protection filters to help protect you from fraudsters using stolen or false credit card information. These filters identify potentially fraudulent activity and let you decide whether to accept or reject the suspicious transaction. Fraud Protection Service can also minimize the risk of hacking your customer database by enabling you to place powerful constraints on access to and use of your PayPal Manager and Payflow Gateway accounts.

PayPal Manager.

You enroll separately for the Fraud Protection Service. You can learn more about Fraud Protection Service in the this service, this user guide will show you how to setup Fraud Protection filters. You can also manage some aspects of your Fraud Protection Service in

Payflow Pro Fraud Protection Services User’s Guide. If you already have

PayPal Manager.

30 07 February 2013 Gateway Developer Guide and Reference

Secure Token

This section describes the secure token.

 “Secure Token” on page 31

 “Integrating the Secure Token With the Hosted Checkout Pages” on page 31

 “Integrating the Secure Token Without the Hosted Checkout Pages: Transparent Redirect”

on page 32

 “Posting To the Hosted Checkout Page” on page 34

 “Using the PARMLIST Parameter” on page 44

About the Secure Token

Use a secure token to send non-credit card transaction data to the Gateway server for safer storage. The secure token prevents anyone from intercepting or manipulating the data. You must use a secure token if you use hosted checkout pages. The token is good for a one-time transaction and is valid for 30 minutes.

NOTE: PayPal Payments Pro and Payflow Pro merchants who do not use a secure token must

host their own payment pages. When hosting your own pages, you are responsible for meeting PCI requirements by handling data securely. PayPal Payments Advanced and Payflow Link merchants must use a secure token with hosted checkout pages.

To obtain a secure token, pass a unique, 36-character secure token ID and set CREATESECURETOKEN=Y in a request to the Gateway server. The Gateway server associates your ID with a secure token and returns the token as a string of up to 32 alphanumeric characters.

To pass the transaction data to the hosted checkout page, you pass the secure token and secure token ID in an HTTP form post. The token and ID trigger the Gateway server to retrieve your data and display it for customer approval.

NOTE: You cannot modify the data sent with a secure token, with one exception. You can

configure PayPal Manager to allow you to modify billing and shipping information.

Integrating the Secure Token With the Hosted Checkout Pages

To create a secure token, pass all parameters that you need to process the transaction except for payment details parameters such as the credit card number, expiration date, and check number. For details on transaction parameters, see “Submitting Credit Card Transactions” on

page 55. In addition, pass the following Payflow parameters to create the secure token.

Gateway Developer Guide and Reference 07 February 2013 31

Secure Token

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

NOTE: The secure token is valid for 30 minutes, and you can only use it one time. If you

attempt to use the token after the time limit has expired, your transaction will fail with Result value 7, “Secure Token Expired.” If you attempt to reuse the token, you receive an error.

1. Set SECURETOKENID to a unique alphanumeric value up to 36 characters in length.

SECURETOKENID=9a9ea8208de1413abc3d60c86cb1f4c5

2. Set CREATESECURETOKEN to the value Y to request that Payflow gateway return a token.

CREATESECURETOKEN=Y

Secure Token Example

The following is an example of a request parameter string that creates a secure token.

TRXTYPE=A&BILLTOSTREET=123 Main St.&BILLTOZIP=95131&AMT=23.45&CURRENCY=USD& INVNUM=INV12345&PONUM=PO9876&CREATESECURETOKEN=Y&SECURETOKENID=9a9ea8208de1 413abc3d60c86cb1f4c5

The Gateway server returns SECURETOKEN and SECURETOKENID in the response. A tag follows the SECURETOKEN to indicate the length of the token value returned.

RESULT=0&RESPMSG=Approved&SECURETOKEN[25]=Fj+1AFUWft0+I0CUFOKh5WA==&SECURET OKENID=9a9ea8208de1413abc3d60c86cb1f4c5

Integrating the Secure Token Without the Hosted Checkout

Pages: Transparent Redirect

To use your own checkout pages while complying with PCI guidelines (sending the customer’s sensitive data directly to the Gateway server), pass all parameters that you need to process the transaction except for sensitive payment details such as the credit card number, expiration date, and check number. For details on sending transactions, see “Submitting Credit

Card Transactions” on page 55.

In addition, pass the following 3 Payflow parameters in your request. The first 2 parameters obtain a secure token. The third parameter implements Transparent Redirect, which suppresses hosted pages.

NOTE: The secure token is valid for 30 minutes, and you can only use it one time. If you

attempt to use the token after the time limit has expired, your transaction will fail with Result value 7, “Secure Token Expired.” If you attempt to reuse the token, you receive an error.

1. Set SECURETOKENID to a unique alphanumeric value up to 36 characters in length.

SECURETOKENID=9a9ea8208de1413abc3d60c86cb1f4c5

32 07 February 2013 Gateway Developer Guide and Reference

Secure Token

Secure Token Errors

2. Set CREATESECURETOKEN to the value Y to request that the Gateway server return a token.

CREATESECURETOKEN=Y

3. Set SILENTTRAN to the value TRUE to suppress the display of hosted pages.

SILENTTRAN=TRUE

Transparent Redirect Example

The following is an example of an authorization parameter string that suppresses hosted pages.

TRXTYPE=A&BILLTOSTREET=123 Main St.&BILLTOZIP=95131&AMT=24.35&INVNUM=INV123 45&PONUM=PO12345&CURRENCY=USD&CREATESECURETOKEN=Y&SECURETOKENID=9a9ea8208de 1413abc3d60c86cb1f4c5&SILENTTRAN=TRUE

The Gateway server returns a SECURETOKEN and SECURETOKENID in the response. A tag follows the SECURETOKEN to indicate the length of the token value returned.

RESULT=0&RESPMSG=Approved&SECURETOKEN[25]=Fj+1AFUWft0+I0CUFOKh5WA==&SECURET OKENID=9a9ea8208de1413abc3d60c86cb1f4c5

When the customer enters their sensitive data into the credit card fields on your website and clicks Submit, the browser posts the data to the Gateway server rather than to your website.

NOTE: It is highly recommended that you add scripting to ensure the the browser posts the

sensitive data directly to the PayPal Gateway server rather than to your website.

If you are using the PARMLIST parameter with the Transparent Redirect, see “Using the

PARMLIST Parameter” on page 44 for more information.

Secure Token Errors

A successful Payflow transaction will return RESULT=0 in the response. If your Secure Token transaction is unsuccessful, you can pass the token 2 more times to Payflow before the token expires.

A Payflow Secure Token will expire:

 If the same Secure Token is passed to Payflow a total of 3 times.

 20 minutes after the Secure Token was generated.

 When the token is used in a successful transaction.

If you receive one of the following error codes in the RESULT response parameter, then your Secure Token has expired.

Gateway Developer Guide and Reference 07 February 2013 33

Secure Token

Posting To the Hosted Checkout Page

160 Secure Token already been used. Indicates that the secure token has expired due to

either a successful transaction or the token has been used three times while trying to successfully process a transaction. You must generate a new secure token.

161 Transaction using secure token is already in progress. This could occur if a

customer hits the submit button two or more times before the transaction completed.

162 Secure Token Expired. The time limit of 20 minutes has expired and the token can no

longer be used.

If you see a different error code in the RESULT parameter, refer to the RESULT Values and

RESPMSG Text section for more information.

Posting To the Hosted Checkout Page

To display the transaction information to the Gateway hosted checkout page, you perform an HTTP form post.

1. Direct the HTTP post to the Gateway applications server at the following URL.

https://payflowlink.paypal.com

2. Send the following parameter data:

– SECURETOKEN returned in the transaction response – SECURETOKENID

HTTP Form Post Examples

The following is an example request string that displays the transaction information to the hosted checkout page.

<html>

<head>

<title>PageTitle</title>

</head>

<body>

<form method="post" action="https://payflowlink.paypal.com"> <input type=hidden value="Fj+1AFUWft0+I0CUFOKh5WA=="

name=SECURETOKEN/>

<input type=hidden value="9a9ea8208de1413abc3d60c86cb1f4c5"

name=SECURETOKENID/>

</form>

</body>

</html>

34 07 February 2013 Gateway Developer Guide and Reference

Secure Token

Posting To the Hosted Checkout Page

For more information on the Payflow parameters that are used to pass information to the Gateway hosted checkout pages, see “Using a Secure Token to Pass Hosted Pages

Customization Parameters” on page 41

The following example uses Payflow name-value pairs to pass values in a form post to the hosted checkout pages. For details on the name-value pair strings used in this example, see

“Sending a Simple Transaction to the Server” on page 51.

<html>

<head>

<title>PageTitle</title>

</head>

<body>

<form method="post" action="https://payflowlink.paypal.com"> <input type="text" name = "SECURETOKEN" value =

"FvwEnHTYRNUSVsZRlhFpudA=="/>

<input type="text" name = "SECURETOKENID" value =

"9a9ea8208de1413abc3d60c86cb1f4c5"/> <input type="hidden" name="PARMLIST" value="INVNUM[8]=INV12345&AMT[5]=25.50&CURRENCY[3]=

USD&PONUM[7]=PO12345"/> <input type="submit"/> </form> </center>

</body></html>

Gateway Developer Guide and Reference 07 February 2013 35

Secure Token

Posting To the Hosted Checkout Page

36 07 February 2013 Gateway Developer Guide and Reference

Configuring Hosted Checkout

Pages

This chapter describes the following:

 “Configuring Hosted Checkout Pages” on page 37

 “Configuring Hosted Pages Using PayPal Manager” on page 37

 “Using a Secure Token to Pass Hosted Pages Customization Parameters” on page 41

 “Hosted Pages and Mobile Browsers” on page 45

 “Silent Posts” on page 47

 “Passing Other Data to Your Server Using Post or Silent Post” on page 48

Configuring Hosted Checkout Pages

PayPal enables you to customize the hosted checkout pages so that they reflect the look and feel of your website. In doing so, the buyer seamlessly transitions from your website to the PayPal hosted checkout pages to make the payment and complete the transaction. Since the pages are hosted on PayPal servers, you do not have to capture or store credit card information on your website, thereby helping towards achieving PCI compliance. PayPal’s hosted checkout pages are optimized for supported desktop and mobile browsers.

NOTE: The Payflow Gateway implementation helps to achieve PCI compliance but does not

necessarily guarantee it.

There are two ways to configure hosted checkout pages:

 Logging in to PayPal Manager and making selections

 Using a secure token and passing configuration parameters in a form post

Configuring Hosted Pages Using PayPal Manager

You can specify the content of your hosted checkout pages and configure their appearance to reflect the look and feel of your website. To do so, log into Service Settings tab. In the Hosted Checkout Pages section, you have the following options:

 Setup

 Customize

 Integrate

PayPal Manager and click on the

Gateway Developer Guide and Reference 07 February 2013 37

Configuring Hosted Checkout Pages

Configuring Hosted Pages Using PayPal Manager

Setup

The Setup page in PayPal Manager enables you to select the information you want to collect from buyers and what you want displayed on your hosted checkout pages. This includes selecting the billing and the shipping information information fields, the payment confirmation page settings, the confirmation email details, security options and other settings.

You can perform tasks such as:

 Configure your PayPal Express Checkout display and specify email addresses for live and

test transactions.

 Determine the cancel URL and the text of the link the buyer clicks on to cancel the

payment on your website. The cancel URL is the page to which PayPal redirects your buyer’s browser if the buyer does not approve the payment.

NOTE: Payflow will ignore the cancel URL field that you entered in PayPal Manager if you

select layout template C. To force Payflow to use the cancel URL field with layout template C, in PayPal Manager, add DISPLAY_URL | before your cancel URL. Example: DISPLAY_URL | http://www.yoursite.com/home.php

 Select the billing and shipping information fields the buyer will be required to complete

during checkout.

 Choose to display a PayPal hosted payment confirmation page or host your own

confirmation page on your website. You can also specify the paypal hosted confirmation page header and footer text and the URL and text for the return link. Additionally, you can choose to enable the silent post feature.

 Opt to send email receipts to the buyer for each successful transaction.

For complete details on these settings, click the Help button on the Setup page. To quickly get get started with your hosted pages, go to the

Hosted Pages Getting Started Guide on the PayPal

38 07 February 2013 Gateway Developer Guide and Reference

developer portal. For more information on the Silent Post feature, go to “Silent Posts” on

page 47

Customize

The Customize page allows you to customize the layout and appearance of your hosted checkout page. You can customize the header, background, payment method section and the order summary column of your payment page. PayPal offers three design layouts for you to choose from. Layout A is the default layout but you can choose any of the three layouts offered (Layouts A, B and C).

Configuring Hosted Checkout Pages

Configuring Hosted Pages Using PayPal Manager

Gateway Developer Guide and Reference 07 February 2013 39

Configuring Hosted Checkout Pages

Configuring Hosted Pages Using PayPal Manager

On the Customize page, you can either change the design of your existing layout, or select and customize a different layout. To make changes, double-click on the section of the template you are trying to modify or the corresponding Click to Edit button for that section. In the pop-up that appears, click the color selector to change the color, or enter the appropriate URL. The customization options vary for the different Layouts. These options are described in greater detail in the next section: Customizing Your Layout.

After making the changes, click one of the following buttons:

 Preview - Preview the changes you have made to your layout before saving and publishing

 Save and Publish - Save all the changes you have made and publish the updated layout.

Your buyers will see the updated payment page.

 Cancel - Discard all the changes you have made in this session.

 Undo Changes - Discard all changes you have made since the last time you saved the

layout. Your buyers will see the last saved layout.

NOTE: You must make all modifications (including changing layouts) within the same

session, otherwise all changes will be lost and you will have to redo your changes. If the session times out, the design of the layout will remain at the version that was last published.

NOTE: Payflow will ignore the cancel URL field that you entered in PayPal Manager if you

Customizing Your Layout

You can customize the appearance of the Layout template that you selected on the customize page. These customizations apply mostly to Layouts A and B. Layout C is embedded on a page you host in an iFrame. So for Layout C, you already control the appearance of the page.

NOTE: These customizations are not applied to the mobile version of the hosted checkout

pages.

 Header (Applicable to Layouts A and B) - You can change the following:

– Header height (Applicable to Layouts A and B) – Header background color (Applicable to Layout B only) – Header font type, size (Applicable to Layouts A and B) – Header font color (Applicable to Layout B only) – Swap between displaying the business name or the business logo image – Edit business name in the header (Applicable to Layouts A and B) – Position of the business name or the logo within the header (left, centered, right)

(Applicable to Layouts A and B)

40 07 February 2013 Gateway Developer Guide and Reference

Configuring Hosted Checkout Pages

Using a Secure Token to Pass Hosted Pages Customization Parameters

 Page Background (Applicable to Layout B only) - You can change the following:

– Background color – Footer text color – Upload a background image - .jpg, .jpeg, .gif, or .png. The maximum allowable image

size is 100kb.

– Repeat image option

 Payment Method Section (Applicable to Layouts B and C) - You can change the following:

– Text color of the section title (Applicable to Layout B only) – Subheader text color (Applicable to Layouts B and C) – Color of other text in this section (Applicable to Layout B only) – Section border color (Applicable to Layouts B and C) – Button color and button text color (Applicable to Layouts B and C)

 Order Summary Column (Applicable to Layout Bonly) - You can change the following:

– Column background color – Upload a background image – Repeat image option

For step-by-step instructions on customizing the appearance of your checkout pages, go to Nate’s blog post on PayPal’s developer portal:

https://www.x.com/node/2750.

Integrate

This section contains links to PayPal developer resources. PayPal’s developer portal includes:

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

 Getting Started Guides that can help get you up and running quickly with a basic integration.

 How-to guides that walk you through a specific integration use case.

 Other useful resources such as blog posts, forums, screencasts, code samples and more.

Using a Secure Token to Pass Hosted Pages Customization

Parameters

Another way to configure your hosted checkout pages is to submit hosted checkout page configuration parameters to the Payflow Gateway in a form post. These parameters will override your hosted checkout page settings in PayPal Manager.

First, you will need to create a secure token. You then pass the secure token with the hosted pages configuration parameters. To learn how to create a secure token, see the Secure Token chapter.

Gateway Developer Guide and Reference 07 February 2013 41

Configuring Hosted Checkout Pages

Using a Secure Token to Pass Hosted Pages Customization Parameters

The table below describes the form post parameters that you can use to dynamically configure the hosted checkout pages.

Setup Params

Variable Description

CANCELURL The URL that customers would go to if pressing a

Cancel link from the hosted page (Layouts A and B only) and from the Express Checkout flow if the buyer chooses Express Checkout as their payment method. Maximum length: 512 characters.

CSCREQUIRED Determines if the card security code is required. Values:

TRUE or FALSE

CSCEDIT Determines if the card security code is editable. Values:

TRUE or FALSE

DISABLERECEIPT Determines if the payment confirmation / order receipt

page is a PayPal hosted page or a page on the merchant site. For carts we recommend the carts host the order confirmation page. Values: TRUE or FALSE

EMAILCUSTOMER Send the buyer an email confirmation or not. Default

value is FALSE.

ERRORURL The URL that customers are directed to if an error

occurs. Maximum length: 512 characters.

RETURNURL The URL that customers are directed to after a

transaction completes successfully. Maximum length: 512 characters.

SILENTPOSTURL The URL to which the Gateway will send Silent Post.

Maximum length: 512 characters.

TEMPLATE Determines whether to use one of the two redirect

templates (Layout A or B) or the embedded template (Layout C). For Layouts A or B pass: TEMPLATEA or TEMPLATEB. Layouts A & B auto-redirect to mobileoptimized pages if a supported mobile browser is detected. No action is required from the merchant for Layouts A & B. For Layout C, pass MOBILE for the mobile-optimized page or MINLAYOUT for the default Layout C embedded template.

URLMETHOD The technical method used to deliver the CANCELURL.

The default is GET and cannot be changed without affecting the installed base, but this value will likely be changed to Post by most carts. Values: POST or GET

42 07 February 2013 Gateway Developer Guide and Reference

Configuring Hosted Checkout Pages

Using a Secure Token to Pass Hosted Pages Customization Parameters

Customize Params

Variable Description

PAGECOLLAPSEBGCOLOR Sets the color of the border around the embedded

template C. Example:

PAGECOLLAPSEBGCOLOR=993300

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

with credit or debit card”. Example:

PAGECOLLAPSETEXTCOLOR=990000

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

Example: PAGEBUTTONBGCOLOR=AA66FF

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

button. Example: PAGEBUTTONTEXTCOLOR=33FFFF

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

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

Using the PARMLIST Parameter

Variable Description

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

summary section. This amount is only for display purposes and is not passed to the transaction servers.

VERBOSITY Additional values returned from the transaction

response to the merchant in the Silent Post. By default, there is no verbosity set which means the standard set of values that Silent Post currently uses is returned. Passing in a verbosity will return the extra values that we get back in the transaction response.Value: HIGH

VERIFY Runs a $0 authorization transaction using the credit card

information the buyer enters. If the $0 authorization is verified, then Payflow will immediately run the transaction for the amount and transaction type you pass to Payflow.Values: TRUE/FALSE

Using the PARMLIST Parameter

PARMLIST is a HTTP Post parameter used with a secure token to pass information to the Gateway hosted checkout pages. PARMLIST takes a string of name-value pairs as its value. Payflow parses out these name-value pairs and uses them to run the transaction. PARMLIST is especially useful for merchants that already use this parameter with the Payflow SDK and want to use an existing name-value pair string.

PARMLIST Example

<html>

<head>

<title>PageTitle</title> </head> <body>

</form> </body>

</html>

44 07 February 2013 Gateway Developer Guide and Reference

If you choose to use PARMLIST, then you can only pass the following 3 HTTP Post parameters to Payflow with PARMLIST: SECURETOKEN, SECURETOKENID and MODE (optional). If you try to pass in any other parameter (such as VERIFY=TRUE), then you will receive an error message.

NOTE: The MODE parameter will be deprecated in the future. If you are using a test secure

token, instead of passing MODE=TEST, change the Form Action attribute value to the testing URL: https://pilot-payflowlink.paypal.com.

If you are using Transparent Redirect with PARMLIST, you must pass the credit card information (ACCT, EXPDATE and CSC) in the PARMLIST. For more information on Transparent Redirect, see “Integrating the Secure Token Without the Hosted Checkout Pages:

Transparent Redirect” on page 32.

Hosted Pages and Mobile Browsers

In PayPal Manager you can select one of 3 hosted pages Layout templates: Layouts A and B (the redirect templates) or Layout C (the embedded template). Layout A is the default Layout.

Configuring Hosted Checkout Pages

Hosted Pages and Mobile Browsers

You can also dynamically select your hosted pages Layout template using the form post TEMPLATE parameter. This will override your default Layout template set in PayPal Manager. Please see Using a Secure Token to Pass Hosted Pages Customization Parameters for more information on passing form post parameters to customize the checkout experience.

Mobile Optimized Checkout Pages

PayPal’s hosted checkout pages are mobile optimized for iPhone, iPod and Android devices. This mobile optimized experience is available for all 3 Layout templates A, B and C. In the case of Layouts A and B, PayPal will auto-detect if the checkout page is being viewed from a supported mobile browser and will redirect to the mobile optimized checkout page. For Layout C, PayPal does not automatically redirect mobile users to a mobile optimized flow. The reason is that if PayPal automatically showed a mobile optimized embedded template, within a merchant web page that may not be mobile optimized, this can create unexpected and undesirable results. To display the mobile checkout page for Layout C, you must detect the

Gateway Developer Guide and Reference 07 February 2013 45

Configuring Hosted Checkout Pages

Hosted Pages and Mobile Browsers

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

The TEMPLATE form post parameter

Layout TEMPLATE parameter value Behavior on a Mobile Device

Layout A TEMPLATE=TEMPLATEA Auto-redirects to mobile optimized

page

Layout B TEMPLATE=TEMPLATEB Auto-redirects to mobile optimized

page

Layout C TEMPLATE=MINLAYOUT (default)

TEMPLATE=MOBILE

The mobile checkout pages are identical for all Layout templates: Layouts A, B and the mobile version of Layout C. Additionally, appearance customizations that you set in submit as form post parameters are not applied to the mobile pages. The figures below show the mobile optimized page flow for a PayPal payment and for a credit card payment:

Mobile page flow for a PayPal payment

Use TEMPLATE=MINLAYOUT for your general online checkout. If you have a mobile optimized experience, explicitly pass TEMPLATE=MOBILE instead to show the mobile optimized page.

PayPal Manager or

46 07 February 2013 Gateway Developer Guide and Reference

Mobile page flow for a credit card payment

Configuring Hosted Checkout Pages

Silent Posts

Silent Post ensures that the transaction data is passed back to your website when a transaction is completed. The Silent Post feature uses the HTML Post method to return data to your server for both approved and declined trasactions. This occurs even if a customer closes the browser before returning to your site, or if the PayPal-hosted payment confirmation page is disabled. Silent Post data is sent to your server at the same time as when a payment confirmation page is displayed or as soon as a transaction is declined.

This feature is configured through

 Go to Service Settings, then from the Hosted Checkout Pages section select Setup

 On the Setup page, set Use Silent Post to Ye s. Then enter the Silent Post URL on your

server.

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

returned by the Silent Post, you must Force Silent Post Confirmation by checking Void transaction when my server fails to receive data sent by the silent post.

Force Silent Post Confirmation

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

https://manager.paypal.com:

Gateway Developer Guide and Reference 07 February 2013 47

Configuring Hosted Checkout Pages

Passing Other Data to Your Server Using Post or Silent Post

sure to check Void transaction when my server fails to receive data sent by the silent post when setting up Silent Posts in PayPal Manager.

Data Returned by the Silent Post Features

The Silent Post feature returns either a short list of data or all of the data that was submitted for the transaction. You can control what is returned to you via the optional ECHODATA parameter:

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

status information on the submitted transaction, set the optional ECHODATA parameter to False. This will return the same values that you receive in a typical transaction response.

(See Transaction Responses for more info).

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

submitted for the transaction, set the optional ECHODATA parameter to True. This is the default setting. This will return the name and address parameters that were provided in the request in addition to the values that you receive in a typical transaction response. (See

Transaction Responses for more info).

Passing Other Data to Your Server Using Post or Silent Post

The USER1 through USER10 Payflow parameters are ten optional string type parameters intended to store your temporary data, such as variables, session IDs, order numbers, and so on. These parameters enable you to pass internal information to your server using the Post or Silent Post feature.

NOTE: USER1 through USER10 are not displayed to the customer and are not stored in the

PayPal transaction database.

48 07 February 2013 Gateway Developer Guide and Reference

Payflow SDK

The Payflow Software Development Kit (SDK) is a set of APIs to allow you to integrate the Gateway with your application or website. This section includes:

 “Preparing the Payflow Gateway Client Application” on page 49.

 “Activating Your Payflow Gateway Account” on page 50.

 “Host URL Addresses” on page 50

NOTE: Each SDK includes full API documentation.

IMPORTANT: The Payflow SDK is available as a .NET or Java library. Using these SDKs is

recommended to simplify integration. Alternately you can build your own API by posting transactions directly to the Gateway servers using HTTPS. See “Posting Transactions Directly Without the Payflow SDK” on page 208 for more information.

Any reference to Payflow SDK or the API in this documentation is referred to simply as the Payflow SDK.

Preparing the Payflow Gateway Client Application

Unless you are building your own API and using HTTPS to post to the servers, you need to obtain the Payflow SDK. Follow these steps.

1. Download the Payflow SDK.

From the your platform.

2. Extract the files to a local directory.

3. Configure your firewall.

If you have a stateful firewall, enable outbound traffic for SSL (port 443). The firewall keeps state on the connection, and automatically permits the inbound response from PayPal.

If you do not have a stateful firewall, enable inbound and outbound traffic for SSL (port

443). Outbound traffic permits the initial Gateway request, while inbound permits the response from PayPal.

4. Read the Readme.txt file.

The Readme.txt file includes integration information and samples that illustrate how to use the client application in your development environment.

SDKs and Downloads page on x.com, download the Payflow SDK appropriate for

Gateway Developer Guide and Reference 07 February 2013 49

Payflow SDK

Activating Your Payflow Gateway Account

When you are ready to activate your Gateway account to begin submitting live transactions, follow these steps:

1. Log in to PayPal Manager at

2. Click ActivateYour Account and follow the on-screen instructions.

3. Change the URL within your web or desktop application to point to the live Gateway

server host addresses.

Host URL Addresses

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

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

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

NOTE: If you are using an older version of the SDK, you will notice that the live and

testing URLs have changed. Be sure to use the URLs mentioned above and remove the “/transaction” from the end of the URL.

Testing Your PayPal Payments Advanced and PayPal Payments Pro Integration

If you have a PayPal Payments Advanced or a PayPal Payments Pro account and you would like to use the testing URL to test your integration, you will first need a PayPal Sandbox test account. If you do not have a Sandbox account, go to instructions to create this account.

https://manager.paypal.com

http://developer.paypal.com and follow the

You will need to enter your Sandbox account information on the Setup page of PayPal Manager

http://manager.paypal.com ( Service Settings -> Hosted Checkout Pages -> Setup).

Fill-in the PayPal Sandbox Email Address field and click Save. You can now test your Payflow Gateway integration against the testing URL: https://pilot- payflowpro.paypal.com.

Passing Information to and Receiving Information from the Hosted Pages

If you would like to pass information to or receive information from the PayPal Hosted Checkout Pages, use one of the following URLs:

 For live transactions, use https://payflowlink.paypal.com

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

NOTE: You no longer need to use the MODE parameter when passing a test secure token.

Instead, post your form parameters to the testing Payflow Link URL. The MODE parameter will be deprecated in the future.

50 07 February 2013 Gateway Developer Guide and Reference

Sending a Simple Transaction to

the Server

When using the Payflow SDK, you send transactions to the Gateway server in name-value pair format. Typically, a simple transaction includes connection parameters, user parameters, and transaction data parameters.

 “About Name-Value Pairs” on page 51

 “Payflow Connection Parameters” on page 52

 “User Parameter Data” on page 53

 “Sale Transaction Example” on page 54

 “Formatting Payflow Gateway Transactions” on page 54

About Name-Value Pairs

Name-value pair (NVP) is the format you use to specify the parameter information you send in a transaction request to the Payflow server. A name-value pair consists of the parameter name and its value. The equal sign (=) is a special character that associates the name and its value:

PARAMNAME=value

Typically, you send several name-value pairs as a parameter string to the server. The ampersand (&) is a special character that separates each name-value pair in the parameter string:

PARAM1NAME=value&PARAM2NAME=value&PARAM3NAME=value

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

Using Special Characters In Values

Because the ampersand (&) and equal sign (=) characters have special meanings, they are invalid in a name-value pair value.

The following are invalid:

COMPANYNAME=Ruff & Johnson

COMMENT1=Level=5

To include special characters in the value portion of a name-value pair, use a length tag. The length tag specifies the exact number of characters and spaces that appear in the value. The following are valid.

Gateway Developer Guide and Reference 07 February 2013 51

Sending a Simple Transaction to the Server

Payflow Connection Parameters

COMPANYNAME[14]=Ruff & Johnson

COMMENT1[7]=Level=5

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

Name-Value Parameter Syntax Guidelines

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

 Do not use spaces in values.

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

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

 Separate all NVPs using an ampersand (&).

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

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

 If you duplicate a parameter in your NVP string, the last item will always be the one used

and the others will be discarded.

Do Not URL Encode Name-Value Parameter Data

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

This example is incorrect:

TRXTYPE%3DS%26TENDER%3DC%26USER%3DMerchantUserID%26PWD%3DPwd4Gateway%26PART NER%3DPayPal%26ACCT%3D5105105105105100%26EXPDATE%3D1215%26AMT%3D23.45%26COM MENT1%3DAirport+Shuttle%26BILLTOFIRSTNAME%3DJamie%26BILLTOLASTNAME%3DMiller %26BILLTOSTREET%3D123+Main+St.%26BILLTOCITY%3DSan+Jose%26BILLTOSTATE%3DCA%2 6BILLTOZIP%3D951311234%26BILLTOCOUNTRY%3DUS%26CVV2%3D123%26CUSTIP%3D0.0.0.0

This example is correct:

TRXTYPE=S&TENDER=C&USER=MerchantUserID&PWD=Pwd4Gateway&PARTNER=PayPal&ACCT= 5105105105105100&EXPDATE=1215&AMT=23.45&COMMENT1=Airport Shuttle&BILLTOFIRS TNAME=Jamie&BILLTOLASTNAME=Miller&BILLTOSTREET=123 Main St.&BILLTOCITY=San Jose&BILLTOSTATE=CA&BILLTOZIP=951311234&BILLTOCOUNTRY=US&CVV2=123&CUSTIP=0.

0.0.0

Payflow Connection Parameters

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

52 07 February 2013 Gateway Developer Guide and Reference

Sending a Simple Transaction to the Server

User Parameter Data

Pass the connection parameters in the format and syntax required by the Payflow SDK and programming language that you are using. See your integration documentation for details.

Parameter Description

HOSTADDRESS (Required) Gateway server name.

HOSTPORT (Required) Use port 443.

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

time-out value of 30 seconds. The client begins tracking from the time that it sends the transaction request to the server.

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

firewall. Your network administrator can provide the values.

PROXYPORT (Optional) Proxy server port.

PROXYLOGON (Optional) Proxy server logon ID.

PROXYPASSWORD (Optional) Proxy server logon password.

In addition to the connection parameters in the table, you must pass the NVP parameters that specify the payment information for the transaction.

User Parameter Data

All Gateway transactions require the user parameters described as follows.

User paramters

Parameter Description

USER (Required) If you set up one or more additional users on the account, this value

is the ID of the user authorized to process transactions. If, however, you have not set up additional users on the account, USER has the same value as VENDOR.

Limitations: 64 alphanumeric, case-sensitive characters

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

account. Limitations: 64 alphanumeric, case-sensitive characters

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

registered you for the Gateway gateway. If you purchased your account directly from PayPal, use PayPal.

Limitations: 64 alphanumeric, case-sensitive characters

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

Limitations: 6 to 32 alphanumeric, case-sensitive characters

Gateway Developer Guide and Reference 07 February 2013 53

Sending a Simple Transaction to the Server

Sale Transaction Example

In addition to the required connection and user parameters, each transaction type may require other parameters and can include a number of optional parameters.

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

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

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

 ACCT - The buyer’s credit card number

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

 EXPDATE - The expiration date of the credit card

Typical Sale Transaction

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

0.0.0&VERBOSITY=HIGH

Besides the required sale transaction parameters, the string includes other Payflow parameters typically included in a sale transaction.

When the transaction completes, the Gateway server returns a response string made up of NVP response parameters. If the transaction is successful, the Gateway server returns RESULT value

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

The following is an example response:

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

Formatting Payflow Gateway Transactions

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

54 07 February 2013 Gateway Developer Guide and Reference

Submitting Credit Card Transactions

When using the Payflow SDK, plan how to implement credit card processing based on your business needs. Payflow SDK offers a core set of transaction parameters that all credit card processors use. This section describes how to submit a transaction for each transaction type supported.

NOTE: Some of the transaction types and features described in this chapter are not supported

by all processors. Be sure to check with your processor for information on the specific functionality that is supported.

 “Obtaining an Internet Merchant Account” on page 56

 “About Credit Card Processing” on page 56

 “Credit Card Features” on page 57

 “Planning Your Gateway Integration” on page 57

 “Core Credit Card Parameters” on page 59

 “Submitting Account Verifications” on page 62

 “Submitting Authorization/Delayed Capture Transactions” on page 63

 “Submitting Balance Inquiry Transactions” on page 64

 “Submitting Card Present (SWIPE) Transactions” on page 65

 “Submitting Credit Transactions” on page 67

 “Submitting Inquiry Transactions” on page 69

 “Submitting Partial Authorizations” on page 72

 “Submitting Purchasing Card Transactions” on page 73

 “Submitting Reference Transactions (Tokenization)” on page 74

 “Submitting Sale Transactions” on page 77

 “Submitting Soft Merchant Information” on page 78

 “Submitting Voice Authorization Transactions” on page 80

 “Submitting Void Transactions” on page 80

 “Using Address Verification Service” on page 82

 “Using Card Security Code” on page 83

Gateway Developer Guide and Reference 07 February 2013 55

Submitting Credit Card Transactions

Obtaining an Internet Merchant Account

To accept credit cards over the internet, you need a special account called an Internet Merchant Account. If PayPal is your merchant bank, you do not need the Internet Merchant Account.

Your account provider or merchant (acquiring) bank works with a PayPal-supported credit card processor. Examples are First Data, TSYS Acquiring Solutions (formerly Vital Processing Services), and Paymentech. To accept live credit cards, provide details about your account to PayPal during the “Go Live” part of enrollment.

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

risks associated with card-not-present (e-commerce) transactions. It is different from a merchant account used for face-to-face/card-present (in-person) retail transactions . Obtain an Internet Merchant Account even if you already accept credit cards at your location.

To apply for an Internet Merchant Account, contact your merchant (acquiring) bank.

About Credit Card Processing

Credit card processing occurs in 2 steps — a real-time authorization and a capture (settlement) of the funds that the cardholder’s issuing bank authorizes. You perform these 2 steps either as a single transaction or as 2 transactions, depending on your business model.

For an authorization, the server sends the transaction information to a credit card processor. The processor routes the transaction through the financial networks to the cardholder’s issuing bank. The issuing bank checks whether the card is valid. It evaluates whether sufficient credit exists, checks values such as address verification service and card security codes, and returns a response such as Approved, Declined, or Referral.

You receive the response a few seconds after you submit the transaction to the server. If the bank approves an authorization, it temporarily reserves the credit for the amount of the transaction to prepare to capture (fulfill) the transaction. The hold on funds typically lasts for about a 3-7 days.

Capturing a transaction actually transfers the funds to your bank. At least once a day, PayPal gathers all transactions flagged for settlement and sends them in a batch file to the processor. The processor then charges the issuing bank and transfers the funds to your bank. It typically takes a few days before the money is available in your account, depending on your bank.

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

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

56 07 February 2013 Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Credit Card Features

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

Transaction Type Billable

Authorization Yes

Account Verification No

Balance Inquiry No

Credit Yes

Delayed Capture No

Inquiry No

Sale Yes

Voice Authorization Yes

Credit Card Features

Vo i d Ye s

The Payflow SDK also supports the following credit card features:

 Address verification service and card security code validation

 Card-present (SWIPE) transactions

 Partial authorizations for pre-paid cards

 Purchasing card transactions

 Reference transactions (also called tokenization)

 Submitting Soft Merchant information

Planning Your Gateway Integration

When designing your Gateway integration, evaluate:

 Whether to use a one-step or two-step transaction process. One-step: Submit a sale

transaction, which performs the authorization and (if successful) then flags the transaction for settlement. Two-step: Perform an authorization-only transaction and then later perform a delayed capture transaction. The delayed capture transaction can be for the same amount as the original transaction or for a lower amount. (In the case of a split shipment, you can perform a delayed capture transaction for the initial shipment and a reference transaction for the final payment.

According to card association rules, most physical goods merchants should use a two-step process, since settlement should occur when the merchant ships the goods. A two-step

Gateway Developer Guide and Reference 07 February 2013 57

Submitting Credit Card Transactions

Planning Your Gateway Integration

process is also useful for evaluating information in the response, such as whether the issuer verifies the billing address, and so on. Electronic goods merchants, who fulfill the order immediately, can use the one-step process. Check with your Internet Merchant Account provider for suggestions on the best method for you.

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

security code. For the address verification service, if the initial transaction submits the data, the issuer checks the street address and the zip code against the billing address on file for the consumer.

Card security code refers to a 3- or 4-digit number that appears on the back of most credit cards. On American Express, the number appears proceeding and to the right of the embossed card number. Card security code is known by other names, such as CVV2, depending on the type of card. If card security code data is submitted, the issuer can notify you whether the number matches the number assigned to the card.

It may also be possible to implement additional safeguards yourself or to use a fraud service. You might want to discuss risk management with your Internet Merchant Account provider.

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

manage the data. You may want to store shipping information in your system, or you may prefer to send the information to PayPal with the transaction and report on it later.

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

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

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

Service, and so on. You may want to integrate your systems directly for capturing funds, issuing refunds/credits, and so on. Alternatively, you may prefer to perform these steps manually using PayPal Manager. Either way, PayPal recommends that you monitor transaction activity using PayPal Manager.

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

the most advantageous rates.

Complying With E-commerce Indicator

Some processors support a software flag called E-commerce Indicator (ECI) that indicates that the associated transaction is an internet transaction. The Payflow SDK complies with ECI basic requirements for all supported processors.

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

Handling Credit Card Type Information

The Payflow SDK does not check the credit card types that you are accepting. If a customer uses a card type you do not accept, the SDK responds with RESULT value 25, “Invalid host mapping,” or the processor returns a message that the customer is not signed up for the card type. Optionally, you can provide your customer with a list of the card types that you accept (in a drop-down list or menu, for example).

58 07 February 2013 Gateway Developer Guide and Reference

Submitting Credit Card Transactions

To accept additional credit card types, contact your acquiring bank (holding your Internet Merchant Account) and ask them to add the card type to your account. Upon notification from your acquirer that you can start accepting the card type, add the card to your Payflow account through PayPal Manager. See PayPal Manager online help for details.

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

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

Core Credit Card Parameters

All credit card processors accept the basic parameters described in the following table with one exception: the PayPal processor does not support SWIPE.

Parameter Description

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

 A = Automated clearinghouse (ACH)  C = Credit card  D = Pinless debit  K = Telecheck  P = PayPal

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

Core Credit Card Parameters

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

 A = Authorization  B = Balance Inquiry  C = Credit  D = Delayed Capture  F = Voice Authorization  I = Inquiry  L = Data Upload  N = Duplicate Transaction

NOTE: A type N transaction represents a duplicate transaction (version 4 SDK or

HTTPS interface only) with a PNREF the same as the original. It appears only in the PayPal Manager user interface and never settles.

 S = Sale  V = Void

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

ACCT=5555555555554444. For the pinless debit TENDER type, ACCT can be the

bank account number. Limitations: This value may not contain spaces, non-numeric characters, or dashes

Gateway Developer Guide and Reference 07 February 2013 59

Submitting Credit Card Transactions

Core Credit Card Parameters

Parameter Description

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

December 2015. Limitations: mmyy format

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

Limitations: Specify the exact amount to the cent using a decimal point. For example, use 34.00 not 34. Do not include comma separators. For example, use 1199.95 not 1,199.95. Your processor or Internet Merchant Account provider may stipulate a maximum amount.

10 numeric characters plus decimal

COMMENT1 (Optional) Merchant-defined value for reporting and auditing purposes.

Limitations: 128 alphanumeric characters

COMMENT2 (Optional) Merchant-defined value for reporting and auditing purposes.

Limitations: 128 alphanumeric characters

CVV2 (Optional) A code printed (not imprinted) on the back of a credit card. Used as partial

assurance that the card is in the buyer’s possession. Limitations: 3 or 4 digits

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

 Y – Identifies the transaction as recurring.  N – Does not identify the transaction as recurring (default).

This value does not activate the Payflow Recurring Billing Service API. If the RECURRING parameter value is Y in the original transaction, this value is ignored when forming credit, void, and force transactions. If you subscribe to the Payflow Fraud Protection Services:

 To avoid charging you to filter recurring transactions that you know are reliable,

the fraud filters do not screen recurring transactions.

 To screen a prospective recurring customer, submit the transaction data using

PayPal Manager’s Manual Transactions page. The filters screen the transaction in the normal manner. If the transaction triggers a filter, follow the normal process to review the filter results.

NOTE: If your transaction is declined and the PAYMENTADVICECODE response

parameter is supported by your processor, a PAYMENTADVICECODE value is returned representing the reason that the transaction was declined. Obtain the meaning of PAYMENTADVICECODE values from your acquiring bank.

Character length and limitations: 1 alpha character

60 07 February 2013 Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Core Credit Card Parameters

Parameter Description

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

data (card’s magnetic stripe information) for card-present transactions. Include either Track 1 or Track 2 data—not both. If Track 1 is physically damaged, the point-of-sale (POS) application can send Track 2 data instead.

The track data includes the disallowed = (equal sign) character. To enable you to use the data, the SWIPE parameter must include a length tag specifying the number of characters in the track data. For this reason, in addition to passing the track data, the POS application must count the characters in the track data and pass that number. Length tags are described in “Using Special Characters In Values” on page 51.

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

Limitations: Alphanumeric and special characters

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

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

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

each other. Use ORDERID with Request ID to prevent duplicates as a result of processing or communication errors.

Character length and limitations: alphanumeric characters

BILLTOFIRSTNAME (Optional) Account holder's first name.

Limitations: 30 alphanumeric characters

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

Limitations: 30 alphanumeric characters

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

The address verification service verifies the STREET address. Limitations: 150 alphanumeric characters

BILLTOCITY (Optional) Bill-to city.

Limitations: 45-character string.

BILLTOSTATE (Optional) Bill-to state.

Limitations: 2-character string (Varies depending on processor: 2 to 45 characters).

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

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

BILLTOCOUNTRY (Optional) Bill-to country.

Limitations: 3-character country code.

SHIPTOFIRSTNAME (Optional) Ship-to first name.

Limitations: 30-character string.

SHIPTOLASTNAME (Optional) Ship-to last name.

Limitations: 30-character string.

Gateway Developer Guide and Reference 07 February 2013 61

Submitting Credit Card Transactions

Submitting Account Verifications

Parameter Description

SHIPTOSTREET (Optional) Ship-to street address.

Limitations: 150-character string.

SHIPTOCITY (Optional) Ship-to city.

Limitations: 45-character string.

SHIPTOSTATE (Optional) Ship-to state.

Limitations: 2-character string (Varies depending on processor: 2 to 45 characters).

SHIPTOZIP (Optional) Ship-to postal code.

Limitations: 10-character string.

SHIPTOCOUNTRY (Optional) Ship-to country.

Limitations: 3-character country code.

Submitting Account Verifications

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

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

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

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

Verified rather than Approved.

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

account verifications.

When To Use Account Verifications

Use account verification to validate account numbers and other authentication elements such as CVV2 and AVS. You can also use an account verification as a reference transaction. See

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

Required Account Verification Parameters

To perform account verification, pass the following parameters:

Parameter Description

TRXTYPE (Required) Set to A.

Limitations: 1 alphanumeric character.

62 07 February 2013 Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Submitting Authorization/Delayed Capture Transactions

Parameter Description

AMT (Required) Set to 0.

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

response.

Example Account Verification String

The following is an example of account verification:

TRXTYPE=A&TENDER=C&PARTNER=PayPal&USER=SuperUser&PWD=SuperUserPasswo rd&AMT=0.00&ACCT=378282246310005&EXPDATE=1215&INVNUM=PONUM1&VERBOSIT Y=HIGH&BILLTOZIP=95031

This is the response:

RESULT=0&PNREF=VFHA0FF8F27D&RESPMSG=Verified&AUTHCODE=667PNI&AVSADDR =X&AVSZIP=X&HOSTCODE=A&PROCAVS=U&AMEXID=123456789012345&AMEXPOSDATA= 123456789012&TRANSTIME=2011-0111 18:42:01&AMT=0.00&ACCT=0005&EXPDATE=1215&CARDTYPE=3&IAVS=X

Submitting Authorization/Delayed Capture Transactions

An authorization (TRXTYPE=A) transaction places a hold on the cardholder’s open-to-buy limit, lowering the cardholder’s limit by the amount of the transaction. It does not transfer funds.

Perform a delayed capture (TRXTYPE=D) transaction after an authorization to capture the original authorization amount. PayPal schedules the delayed capture for settlement during the next settlement period.

Because Visa and MasterCard regulations prohibit capturing credit card payments until the buyer receives the product or service, most processing networks implement an authorization followed by a delayed capture.

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

transactions unless they obtain the Payflow SDK.

When to Use Authorization/Delayed Capture Transactions

If your business does not provide immediate fulfillment of products or services, PayPal recommends that you use delayed capture processing. It enables you to capture credit card payments when you are ready to collect them.

NOTE: If you signed up for the PayPal processor with Fraud Protection Services, use delayed

capture processing for all sale transactions.

Gateway Developer Guide and Reference 07 February 2013 63

Submitting Credit Card Transactions

Submitting Balance Inquiry Transactions

If your business provides immediate fulfillment and you are not using the PayPal processor with Fraud Protection Services, you can use a simple sale transaction instead. For details, see

“Submitting Sale Transactions” on page 77. To recharge a credit card when you are not storing

credit card information in your local database, perform a new reference transaction based on a sale. For details, see “Submitting Reference Transactions (Tokenization)” on page 74.

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

transaction.

Required Authorization Transaction Parameters

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

Parameter Description

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

The PNREF parameter returns this ID, and it appears as the Transaction ID in PayPal Manager reports.

Limitations: 12 case-sensitive alphanumeric characters.

Typical Authorization Transaction Parameter String

A typical NVP string passed in an authorization transaction is the same as a sale transaction string. The only difference is that the TRXTYPE value is A in an authorization.

TRXTYPE=A&TENDER=C&USER=SuperUser&PWD=SuperUserPassword&VENDOR=SuperUser&PA RTNER=PayPal&ACCT=5105105105105100&EXPDATE=1215&CVV2=123&AMT=99.00&BILLTOFI RSTNAME=John&BILLTOLASTNAME=Smith&BILLTOSTREET=123 Main St.&BILLTOCITY=San Jose&BILLTOSTATE=CA&BILLTOZIP=12345&COMMENT1=Reservation&INVNUM=1234567890& PONUM=C12345&VERBOSITY=HIGH

Submitting Balance Inquiry Transactions

Balance Inquiry (TRXTYPE=B) transactions are used to obtain the balance of a pre-paid card. This transaction type is different from a balance inquiry performed during an authorization transaction. However, both of these transaction types will return the balance in the BALAMT response parameter.

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

support balance inquiry.

64 07 February 2013 Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Submitting Card Present (SWIPE) Transactions

Processing Platforms Supporting Balance Inquiry Transactions

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

World Pa y

Required Balance Inquiry Parameters

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

Parameter Description

TRXTYPE (Required) Set to B.

Limitations: 1 alphanumeric character.

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

example, 1215 represents December 2015.

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

response.

Example Balance Inquiry Transaction String

The following is an example of a balance inquiry transaction:

TRXTYPE=B&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperUser&PWD=S uperUserPassword&ACCT=5555555555554444&EXPDATE=1215&VERBOSITY=HIGH

This is the response:

RESULT=0&PNREF=ERRV0A005933&RESPMSG=Approved&AUTHCODE=467PNI&HOSTCODE=000&T RANSTIME=2012-0216 18:41:25&AMT=0.00&BALAMT=10.00&ACCT=4444&EXPDATE=1215&CARDTYPE=0

Submitting Card Present (SWIPE) Transactions

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

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

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

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

transactions.

Gateway Developer Guide and Reference 07 February 2013 65

Submitting Credit Card Transactions

Submitting Card Present (SWIPE) Transactions

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

accepting and passing swipe data.

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

separate Gateway accounts. Request that one account be set up for card-present transactions, and use it solely for that purpose. Use the other for card-not-present transactions. Using the wrong account may result in downgrades.

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

acquiring bank for recommendations on other methods.

Processing Platforms Supporting Card-Present Transactions

The following processing platforms support card-present transactions.

American Express

American Express APAC

Elavon

First Data Merchant Services (FDMS) Nashville

First Data Merchant Services (FDMS) North

First Data Merchant Services (FDMS) South

Global Payments Central

Global Payments East

Heartland Payment Systems

Litle

Merchant e-Solutions

Moneris Solutions

Paymentech Salem

Paymentech Tampa

PayPal

SecureNet

TeleCheck

TSYS Acquiring Solutions

Va nt iv

World Pa y

66 07 February 2013 Gateway Developer Guide and Reference

Card Present Transaction Syntax

Use the SWIPE parameter to pass the Track 1 or Track 2 data (the card’s magnetic stripe information). Include either Track 1 or Track 2 data (up to 80 alphanumeric characters). If Track 1 is physically damaged, the POS application can send Track 2 data instead.

The track data includes the disallowed = (equal sign) character. To enable you to use the data, the SWIPE parameter must include a length tag specifying the number of characters in the track data. For this reason, in addition to passing the track data, the POS application counts the characters in the track data and passes that number as the length tag. For details on length tags, see “Using Special Characters In Values” on page 51. The length tag in the following example is [40].

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

SWIPE value includes this data.

TRXTYPE=S&TENDER=C&PARTNER=PayPal&USER=SuperMerchant&PWD=SuperMerchant&SWIP E[40]=;4912000033330026=15121011000012345678?&AMT=21.00

Submitting Credit Card Transactions

Submitting Credit Transactions

The credit transaction (TRXTYPE=C) refunds the specified amount back to the cardholder. A credit transaction can contain a reference to the original transaction (referenced) or not (nonreferenced) depending on how your account is setup. To issue a credit, the original transaction can only be one of the following: a Sale (TRXTYPE=S), Delayed Capture (TRXTYPE=D) or Voice Authorization (TRXTYPE=F). It is recommended that the merchant issue a credit only if the original transaction has already settled. Even though it is possible to issue a credit to a transaction that has not settled, it is recommended that you void such transactions.

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

Required Credit Transaction Parameters

The required parameter data for a credit transaction depends on the Allow non-referenced credits security setting for your Payflow account. A non-referenced credit is a credit

transaction that does not use the credit card information from an existing transaction. You provide the credit card information. As an example, Sally Smith calls you on the phone to cancel an order from your business. To refund her money, you credit her credit card by submitting a non-referenced credit transaction.

Guidelines and parameter requirements for credit transactions differ depending on whether non-referenced credits are allowed.

Non-Referenced Credits Not Allowed

When non-referenced credits are not allowed (the setting recommended by PayPal), credit transactions are permitted only against existing sale, delayed capture, and voice authorization

Gateway Developer Guide and Reference 07 February 2013 67

Submitting Credit Card Transactions

Submitting Credit Transactions

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

Parameter Description

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

The PNREF parameter returns this ID, and it appears as the Transaction ID in PayPal Manager reports.

Limitations: 12 case-sensitive alphanumeric characters.

Set the value of ORIGID to the PNREF value returned for the original transaction. (PayPal Manager reports display the PNREF as the Transaction ID.) If you do not specify an amount, the amount of the original transaction is credited to the cardholder.

Non-Referenced Credits Allowed

When non-referenced credits are allowed, credit transactions are permitted in any amount up to the transaction limit for the credit card account that you specify. To submit a credit transaction when non-referenced credits are allowed, you must pass values for the following parameters:

 ACCT

 EXPDATE

 AMT

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

No. Sending the ORIGID is the preferred method for performing credit transactions. Using the ACCT, EXPDATE, or AMT parameters for such accounts leads to the return of RESULT value 117 (failed the security check). To help reduce fraud, PayPal recommends that you not activate non-referenced credits unless you have a business reason. For information on setting the security settings, see PayPal Manager online help.

Parameter Description

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

referenced. The PNREF parameter returns this ID, and it appears as the Transaction ID in PayPal Manager reports.

Limitations: 12 case-sensitive alphanumeric characters

Set the value of ORIGID to the PNREF value returned for the original transaction. (PayPal Manager reports display the PNREF as the Transaction ID.) If you do not specify an amount, then the amount of the original transaction is credited to the cardholder.

68 07 February 2013 Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Submitting Inquiry Transactions

Fields Copied From the Original Transaction Into the Credit Transaction

The following fields are copied from the original transaction into the credit transaction (if they exist in the original transaction). If you provide a new value for any of these parameters when submitting the credit transaction, the new value is used. (Exceptions are ACCT, EXPDATE, and SWIPE. These parameters retain their original values.)

NOTE: These fields are not copied for referenced credits: TAXAMT, TAXEXEMPT, DUTYAMT,

FREIGHTAMT, and (for American Express only) DESC4.

NOTE: For processors that use the RECURRING parameter: If you set the RECURRING

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

ACCT AMT BILLTOCITY BILLTOCOUNTRY

BILLTOEMAIL BILLTOMIDDLENAME BILLTOLASTNAME BILLTOPHONENUM

BILLTOSTATE BILLTOSTREET BILLTOZIP COMMENT1

COMMENT2 COMPANYNAME CUSTCODE CUSTIP

EXPDATE INVNUM PONUM SHIPTOCITY

SHIPTOCOUNTRY SHIPTOFIRSTNAME SHIPTOMIDDLENAME SHIPTOLASTNAME

SHIPTOSTATE SHIPTOSTREET SHIPTOZIP SWIPE

Example Credit Transaction Parameter Strings

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

TRXTYPE=C&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant&P WD=x1y2z3&ORIGID=VPNE12564395

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

TRXTYPE=C&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant&P WD=x1y2z3&ACCT=5555555555554444&EXPDATE=1215&AMT=123.00&VERBOSITY=HIGH

Submitting Inquiry Transactions

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

Gateway Developer Guide and Reference 07 February 2013 69

Submitting Credit Card Transactions

Submitting Inquiry Transactions

When To Use an Inquiry Transaction

You perform an inquiry using a reference to an original transaction—either the PNREF value returned for the original transaction or the CUSTREF value that you specified for the original transaction. You can also perform an inquiry using the secure token.

While the amount of information returned in an inquiry transaction depends upon the VERBOSITY setting, inquiry responses mimic the verbosity level of the original transaction as closely as possible.

Required Parameters When Using the PNREF

To perform an inquiry, pass the following parameter:

Parameter Description

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

The PNREF parameter returns this ID, and it appears as the Transaction ID in PayPal Manager reports.

Limitations: 12 case-sensitive alphanumeric characters.

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

Inquiry Transaction Parameter String Using the PNREF

This is an example inquiry transaction parameter string using the ORIGID parameter set to the PNREF value:

TRXTYPE=I&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant&P WD=x1y2z3&ORIGID=VPNE12564395&VERBOSITY=HIGH

Required Parameters When Using the CUSTREF

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

Parameter Description

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

example, you can set CUSTREF to the invoice number. You can use CUSTREF when performing inquiry transactions. To make sure that

you can always access the correct transaction when performing an inquiry, provide a unique CUSTREF when submitting any transaction, including retries.

Limitations: 12 alphanumeric characters

70 07 February 2013 Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Submitting Inquiry Transactions

Parameter Description

STARTTIME (Optional) For inquiry transactions when using CUSTREF to specify the

transaction. STARTTIME specifies the beginning of the time period during which the

transaction specified by the CUSTREF occurred. ENDTIME must be less than 30 days after STARTTIME. You cannot perform an

inquiry across a date range greater than 30 days. If you set ENDTIME, and not STARTTIME, STARTTIME defaults to 30 days

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

days. Limitations: 14 numeric characters in the format yyyymmddhhmmss

ENDTIME (Optional) For inquiry transactions when using CUSTREF to specify the

transaction. ENDTIME specifies the end of the time period during which the transaction

specified by the CUSTREF occurred. Limitations: 14 numeric characters

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

last transaction only with the specified CUSTREF. To make sure that you can always access the correct transaction, use a unique CUSTREF when submitting any transaction, including retries.

Inquiry Transaction Parameter String Using the CUSTREF

This is an example inquiry parameter string using the CUSTREF.

TRXTYPE=I&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant &PWD=x1y2z3&CUSTREF=Inv00012345

Required Parameters When Using the Secure Token

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

Parameter Description

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

transaction data. Limitations: 32 alphanumeric characters

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

Gateway Developer Guide and Reference 07 February 2013 71

Submitting Credit Card Transactions

Submitting Partial Authorizations

Inquiry Parameter String Using the Secure Token

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

TRXTYPE=I&TENDER=C&PARTNER=PayPal&PWD=SuperUserPassword&USER=SuperMerchant& VERBOSITY=HIGH&VENDOR=SuperMerchant&SECURETOKEN=FmyM1y7wy8kiS6aumnMPhTQN&VE RBOSITY=HIGH

The following is the response string.

RESULT=0&PNREF=VFHE1A0CB0A9&TRANSSTATE=6&ORIGRESULT=0&ORIGPNREF=VFHE1A0CB0A 8&RESPMSG=Approved&AUTHCODE=010101&AVSADDR=Y&AVSZIP=Y&HOSTCODE=00&PROCAVS=Y &DATE_TO_SETTLE=2011-02-04 16:16:50&TRANSTIME=2011-0204 16:16:50&BILLTOFIRSTNAME=James&BILLTOLASTNAME=Smith&AMT=555.00&ACCT=0002 &EXPDATE=0120&CARDTYPE=0&IAVS=N

Submitting Partial Authorizations

A partial authorization is a partial approval of an authorization (TRXTYPE=A) transaction. A partial authorization approves a transaction when the balance available is less than the amount of the transaction. The transaction response returns the amount of the original transaction and the amount approved.

When To Use Partial Authorizations

Use partial authorizations to reduce the number of declines resulting from buyers spending more than their balance on prepaid cards.

Say, for example, that you sell sportswear on your website. Joe purchases a pair of running shoes in the amount of $100.00. At checkout, Joe uses a giftcard with a balance of $80.00 to pay. You request partial authorization of $100.00. The transaction response returns the original amount of $100.00 and the approved amount of $80.00.

You can take either of the following actions:

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

$20.00.

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

(Void) for $80.00.

Required Partial Authorization Parameters

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

72 07 February 2013 Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Submitting Purchasing Card Transactions

Parameter Description

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

Limitations: 1 alphanumeric character.

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

response.

Example Partial Authorization

The following is an example partial authorization.

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

TRXTYPE=A&TENDER=C&AMT=100.00&ACCT=4111111111111111&EXPDATE=0119 &PARTIALAUTH=Y&VERBOSITY=HIGH

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

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

RESULT=0&PNREF=VRNS1A3B33C9&RESPMSG=Partial Approval&AUTHCODE=11111&HOSTCODE=E&PROCAVS=U&TRANSTIME=2010-04-21

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

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

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

Since the amount charged is greater than the amount available on the card, the response sets the balance amount (BALAMT) to zero. If BALAMT is zero, check if there is a balance due by comparing the original amount to the amount charged (ORIGAMT-AMT).

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

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

$20.00.

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

(void) for $80.

Submitting Purchasing Card Transactions

A purchasing card (also referred to as a commercial card, corporate card, procurement card or business card) is a credit card that an employer requests to be issued. A purchasing card is usually reserved for business-related charges. The card issuer provides specialized reporting for this card type so the employer can monitor the use of the card. There is no method for determining whether a card is a purchase card or a commercial card based on the card number.

Gateway Developer Guide and Reference 07 February 2013 73

Submitting Credit Card Transactions

Submitting Reference Transactions (Tokenization)

To obtain the best bank interchange rates for commercial cards, pass specific additional transaction information. Purchasing card support and parameters vary from processor to processor. See “Submitting Purchasing Card Level 2 and 3 Transactions” on page 151.

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

Submitting Reference Transactions (Tokenization)

To recharge a credit card when you are not storing the credit card information in your local database, you can perform a reference transaction. A reference transaction takes the existing credit card information that is on file and reuses it. (Securely storing data for future reference is also known as tokenization.)

The PNREF returned in the original transaction is valid for use in reference transactions for 12 months. You can also use the PNREF account verification returns in a reference transaction.

When To Use a Reference Transaction

Say that Joe Smith purchases a holiday gift from your website store and requests that you send it by UPS ground service. That evening, Joe becomes concerned that the item might not arrive in time for the holiday. So Joe calls you to upgrade shipping to second-day air. You obtain Joe’s approval for charging an extra $10 for the upgrade. In this situation, you can create a reference transaction based on the original authorization and charge an additional $10 to Joe’s credit card without having to ask him again for credit card information.

NOTE: As a security measure, reference transactions are disallowed by default. Only your

account administrator can enable reference transactions for your account. If you attempt to perform a reference transaction in an account that does not allow reference transactions, Payflow returns RESULT value 117. See PayPal Manager online help for instructions on setting reference transactions and other security features.

Sale and authorization transactions can use a reference transaction as a source of transaction data. Payflow looks up the reference transaction and copies its transaction data into the new sale or authorization. Fraud Protection Service filters do not screen reference transactions.

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

transaction referenced or any other transaction in the database. A reference transaction is a read-only operation. Payflow populates with data and acts upon the new transaction only. It does not maintain any linkage between the reference transaction and the new transaction.

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

74 07 February 2013 Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Submitting Reference Transactions (Tokenization)

Transaction Types That Can Be Used As the Original Transaction

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

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

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

 Credit

 Delayed capture

 Sale

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

transaction)

 Vo i d

Fields Copied From Reference Transactions

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

ACCTTYPE BILLTOSTREET

ACCT BILLTOCITY

EXPDATE BILLTOSTATE

BILLTOFIRSTNAME BILLTOZIP

BILLTOMIDDLENAME BILLTOCOUNTRY

BILLTOLASTNAME SWIPE

Example Reference Transaction

In this example, you authorize an amount of $100 for a shipment and charge $66 for the first partial shipment using a normal delayed capture. You charge the $34 for the final part of the shipment using a reference transaction to draw credit card and shipping address information from the initial authorization transaction.

This example procedure creates a reference transaction:

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

You use an authorization transaction for the full amount of the purchase of $100 as shown in this transaction request:

Gateway Developer Guide and Reference 07 February 2013 75

Submitting Credit Card Transactions

Submitting Reference Transactions (Tokenization)

TRXTYPE=A&TENDER=C&PWD=x1y2z3&PARTNER=PayPal&VENDOR=SuperMerchant&USER=Supe rMerchant&ACCT=5555555555554444&EXPDATE=1215&AMT=100.00&INVNUM=123456789&BI LLTOSTREET=5199 MAPLE&BILLTOZIP=94588

Note the value of the PNREF in the response:

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

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

12 months.

2. Capture the authorized funds for a partial shipment of $66.

When you deliver the first $66 worth of product, you use a normal delayed capture transaction to collect the $66. Set ORIGID to the value of PNREF in the original authorization as in this transaction request.

TRXTYPE=D&TENDER=C&PWD=x1y2z3&PARTNER=PayPal&VENDOR=SuperMerchant&USER=Supe rMerchant&ORIGID=VXYZ01234567&AMT=66.00

The following is the response:

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

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

When you ship the remainder of the product, you can collect the remaining $34 in a sale transaction that uses the initial authorization as a reference transaction. (This is a sale transaction, because Payflow allows only one delayed capture transaction per authorization.)

The following is a sale transaction request:

TRXTYPE=S&TENDER=C&PWD=x1y2z3&PARTNER=PayPal&VENDOR=SuperMerchant&USER=Supe rMerchant&ORIGID=VXYZ01234567&AMT=34.00

The following is the response:

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

Data Upload - Storing Credit Card Data on the Gateway Server

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

 TRXTYPE

 TENDER

 ACCT

76 07 February 2013 Gateway Developer Guide and Reference

Submitting Credit Card Transactions

Submitting Sale Transactions

 EXPDATE

This is an example upload transaction request:

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

This is the response:

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

You can send shipping and billing information to be stored, but you must not include the AMT field. If you pass a value for AMT, you will receive an error with RESULT=4 and RESPMSG=Invalid Amount.

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

To validate a transaction, you must submit an account verification, also known as a zero dollar authorization (TRXTYPE=A). For details, see “Submitting Account

Verifications” on page 62.

Submitting Sale Transactions

The sale transaction (TRXTYPE=S) charges the specified amount against the account, and marks the transaction for immediate fund transfer during the next settlement period. PayPal submits each merchant’s transactions for settlement on a daily basis.

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

unless they obtain the Payflow SDK.

When To Use a Sale Transaction

A sale transaction is best suited to businesses that provide immediate fulfillment for their products or services. If your business does not provide immediate fulfillment, credit card association rules recommend that you use an authorization and a delayed capture transaction. For details, see “Submitting Authorization/Delayed Capture Transactions” on page 63. To recharge a credit card when you are not storing the credit card information in your local database, you can perform a new reference transaction based on a Sale transaction.

Additional Parameters For Sale Transactions

To perform a sale transaction, pass the following parameters:

 ACCT

 AMT

 EXPDATE

Gateway Developer Guide and Reference 07 February 2013 77

Submitting Credit Card Transactions

Submitting Soft Merchant Information

NOTE: The pinless debit tender type requires essentially the same parameters as a credit card

transaction. In addition to the values required by all transactions, pass values for the ACCT and AMT parameters. The First Data Merchant Services (FDMS) South processing platform supports sale and credit transactions only.

Typical Sale Transaction Parameter String

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

TRXTYPE=S&TENDER=C&USER=SuperUser&PWD=SuperUserPassword&VENDOR=SuperUser&PA RTNER=PayPal&ACCT=5105105105105100&EXPDATE=1215&CVV2=123&AMT=99.00&BILLTOFI RSTNAME=John&BILLTOLASTNAME=Smith&BILLTOSTREET=123 Main St.&BILLTOCITY=San Jose&BILLTOSTATE=CA&BILLTOZIP=12345&COMMENT1=Reservation&INVNUM=1234567890& PONUM=C12345&VERBOSITY=HIGH

Besides the required parameters that you pass in a sale transaction, this string includes other typical parameters. The COMMENT1 (and COMMENT2) fields help to track transaction information. Pass the customer’s street address (BILLTOSTREET) and zip code (BILLTOZIP) to use address verification service. To validate card security codes, pass the CVV2 parameter. For details on address verification service and card security code, see the following:

 “Submitting Card Present (SWIPE) Transactions” on page 65

 “Using Card Security Code” on page 83

Submitting Soft Merchant Information

Soft merchant information is detailed data about a merchant such as the merchant’s name, business address, business location identifier, and contact information.

About Soft Merchant Information

Merchants aggregators, who perform transactions on behalf of other merchants under a single merchant account, provide the processor with soft merchant information. Soft merchant information identifies the merchant making the sale and includes information about that merchant on the buyer’s card statement.

Say, for example, Outdoor Apparel has a chain of 12 stores located in the Western United States with the corporate office in Oakland, California. John Lui purchases a pair of hiking boots online from Hiker’s Duds in San Jose, California, and charges them to his credit card. The transaction goes to the aggregator at Outdoor Apparel in Oakland. The aggregator sends soft merchant information about the Hiker’s Duds store with the transaction to the credit card processor. When John receives his credit card statement, he recognizes the charge for the hiking boots he purchased at Hiker’s Duds in San Jose.

78 07 February 2013 Gateway Developer Guide and Reference

Ways to Send Soft Merchant Information

There are 2 ways you can send soft merchant information:

 Soft merchant information (SM Record)

 Merchant descriptor (M Record)

The Paymentech processor requires that you follow their guidelines to send soft descriptor information using either of these methods.

Soft Merchant Information (SM Record)

Soft merchant information is for American Express credit cards only. Typically aggregators (and petroleum merchants) pass soft merchant information to the processor in Gateway parameter fields such as the following:

 MERCHANTNAME

 MERCHANTSTREET

 MERCHANTCITY

 MERCHANTSTATE

Submitting Credit Card Transactions

Submitting Soft Merchant Information

 MERCHANTNAME

 MERCHANTZIP

 MERCHANTCOUNTRYCODE

 MERCHANTLOCATIONID

 MERCHANTID

 MERCHANTCONTACTINFO

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

you must be approved by the Paymentech Risk/Credit department. Upon approval, Paymentech sets a flag at the transaction division to enable you to send the preceding parameters. If the flag is not set and you send the parameters, your transaction is rejected with Error 258.

Merchant Descriptor (M Record)

A merchant descriptor defines the merchant name and product that appears on the account holder’s statement. The descriptior information is passed to the processor in parameter fields such as the following:

 MERCHDESCR – Defines the merchant name and product

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

number, e-mail address, or website URL

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

Gateway Developer Guide and Reference 07 February 2013 79

Submitting Credit Card Transactions

Submitting Voice Authorization Transactions

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

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

When To Use a Voice Authorization Transaction

Some transactions cannot be authorized over the Internet (for example, high dollar amounts) and require manual authorization. These referral transactions generate RESULT value 13.

In these situations, you contact the customer service department of your merchant bank and provide the payment information as requested. If the bank approves the transaction, the bank provides you with a voice authorization code (AUTHCODE) for the transaction..

On approval, a voice authorization transaction is treated like a sale transaction and is settled with no further action on your part.

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

Required Voice Authorization Transaction Parameters

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

Parameter Description

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

authorization transactions. AUTHCODE is the approval code received over the phone from the processing network.

Limitations: 6 alphanumeric characters

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

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

Submitting Void Transactions

The void transaction (TRXTYPE=V) prevents authorizations from being captured, and delayed captures, sales and voice authorizations from being settled.

You cannot void another void transaction or any inquiry type transactions. The void transaction and the original transaction will not appear on the customer’s statement.

80 07 February 2013 Gateway Developer Guide and Reference

PayPal will issue an authorization reversal as part of the void transaction for debit and credit cards if the processor supports it. Because the bank or issuer ultimately decides whether to honor authorization reversals, there is no accurate way to determine if an authorization reversal was completed and the hold on funds has been removed.

When To Use a Void Transaction

Use the following guidelines when using void transactions:

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

transactions. You cannot void a void transaction.

 You can only use a void transaction on a transaction that has not yet settled. To refund a

customer’s money for a settled transaction, submit a credit transaction.

Required Void Transaction Parameters

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

Submitting Credit Card Transactions

Submitting Void Transactions

Parameter Description

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

referenced. The PNREF parameter returns the ID, and it appears as the Transaction ID in PayPal Manager reports.

Limitations: 12 case-sensitive alphanumeric characters

Fields Copied From the Original Transaction Into the Void Transaction

The following fields are copied from the original transaction into the void transaction (if they exist in the original transaction). If you provide a new value for any of these parameters when submitting the void transaction, the new value is used. (Exceptions are ACCT, EXPDATE, and SWIPE. These parameters retain their original values.)

NOTE: For processors that use the RECURRING parameter: If you set the RECURRING

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

ACCT AMT BILLTOCITY COMMENT1

COMMENT2 COMPANYNAME BILLTOCOUNTRY CUSTCODE

CUSTIP DUTYAMT BILLTOEMAIL EXPDATE

BILLTOFIRSTNAME BILLTOMIDDLENAME BILLTOLASTNAME FREIGHTAMT

INVNUM PONUM SHIPTOCITY SHIPTOCOUNTRY

Gateway Developer Guide and Reference 07 February 2013 81

Submitting Credit Card Transactions

Using Address Verification Service

SHIPTOFIRSTNAME SHIPTOMIDDLENAME SHIPTOLASTNAME SHIPTOSTATE

SHIPTOSTREET SHIPTOZIP BILLTOSTATE BILLTOSTREET

SWIPE TAXAMT BILLTOPHONENUM TAXEXEMPT

BILLTOZIP

Example Void Transaction Parameter String

The following is an example void transaction string:

TRXTYPE=V&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant&P WD=x1y2z3&ORIGID=VPNE12564395&VERBOSITY=HIGH

Using Address Verification Service

To qualify for the lowest bank rate, pass address verification service information, including the street address and zip (postal) code.

Address verification service compares the submitted billing street address and zip code with the values on file at the cardholder’s bank. The response includes values for AVSADDR and

AVSZIP: Y, N, or X for the match status of the customer’s street address and zip code. Y = match, N =nomatch, X = cardholder’s bank does not support address verification service.

The address verification service result is for advice only. Banks do not decline transactions based on the address verification service result. The merchant decides to approve or decline a transaction. Most US banks and some international banks support the address verification service.

NOTE: Address verification service checks only for a street number match, not a street name

match, so 123 Main Street returns the same response as 123 Elm Street.

The international address verification service (IAVS) response indicates whether the address verification service response is international (Y), USA (N), or cannot be determined (X).

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

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

Example Address Verification Service Parameter String

This example request includes the address verification service parameters BILLTOSTREET and BILLTOZIP:

TRXTYPE=A&TENDER=C&PWD=SuperUserPassword&PARTNER=PayPal&VENDOR=Vendor&USER= SuperMerchant&&ACCT=5555555555554444&EXPDATE=1215&AMT=123.00&BILLTOSTREET=5 199 Maple&BILLTOZIP=98765

82 07 February 2013 Gateway Developer Guide and Reference

In this example response, the address value matches the value in the bank’s records, but the

zip code does not. The AVSZIP response is N.

RESULT=0&PNREF=VXW412345678&RESPMSG=APPROVED&AUTHCODE=123456&AVSADDR=Y&AVSZ IP=N&IAVS=X

Using Card Security Code

The card security code is a 3- or 4-digit number (not part of the credit card number) that is printed on the credit card. Because the card security code appears only on the card and not on receipts or statements, the code provides some assurance that the physical card is in the buyer’s possession.

This fraud prevention tool has various names, depending on the payment network. Visa calls it CVV2, MasterCard calls it CVC2 while American Express and Discover call it CID. To make sure that your customers see a consistent name, PayPal recommends use of the term card security code on all end-user materials.

Submitting Credit Card Transactions

Using Card Security Code

On most cards (Diners Club, Discover, Mastercard and Visa) the card security code is a 3-digit number printed on the back of the card (usually in the signature field). All or part of the card number appears before the card security code (567 in the example). American Express prints a 4-digit number (1122 in the example) on the front of the card, above and to the right of the embossed account number. Make sure that you explain this to your customers.

To validate the card security code in a transaction, pass the card security code value in the CVV2 parameter in your request. The response parameter CVV2MATCH returns the result of the card security code check.

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

value that you pass in the CVV2 parameter.

Card security code

The following is an example request parameter string.

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

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

Gateway Developer Guide and Reference 07 February 2013 83

Submitting Credit Card Transactions

Using Card Security Code

84 07 February 2013 Gateway Developer Guide and Reference

Testing Transactions

Before you activate your website or application for use by buyers, test your integration. A simulated payment network handles transactions, enabling you to verify the configuration and operation of your website or application. No money changes hands.

Setting Up The Payflow Gateway Testing Environment

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

Direct all transactions to the host URL for testing. See “Host URL Addresses” on page 50. PayPal’s simulated network processes transactions directed to the URL.

Testing Guidelines

Follow these guidelines for testing.

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

error.

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

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

Processors Other Than PayPal

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

Credit Card Numbers for Testing

For processors other than PayPal, use the following credit card numbers for testing. Any other card number produces a general failure.

American Express 378282246310005

American Express 371449635398431

American Express Corporate 378734493671000

Gateway Developer Guide and Reference 07 February 2013 85

Testing Transactions

Processors Other Than PayPal

Diners Club 38520000023237

Discover 6011111111111117

Discover 6011000990139424

JCB 3530111333300000

JCB 3566002020360505

MasterCard 5555555555554444

MasterCard 5105105105105100

Visa 4111111111111111

Visa 4012888888881881

Visa 4222222222222

NOTE: Even though this number has a different character

count than the other test numbers, it is the correct and functional number.

Result Values Based On Amount Submitted

You can use the amount of the transaction to generate a particular result value. The following table lists the general guidelines for specifying amounts to submit in requests.

Amount Result

$0 – $1000 RESULT value 0 (Approved)

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

the results by adding $1000 to that RESULT value. For example, for RESULT value 13 (Referral), submit the amount 1013.

If the amount is in this range but does not correspond to a result supported by this testing mechanism, Payflow returns RESULT value 12 (Declined).

$2001+ RESULT value 12 (Declined)

Result Values Based On Amount Submitted and Processor

This table lists the RESULT values that you can generate using the amount of the transaction. To generate a specific value, submit an amount of 1000 plus the RESULT value number (for example, submit an amount of 1013 for a RESULT value of 13).

Processing Platform RESULT Values Available for Testing

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

Elavon 0, 12, 13, 104

86 07 February 2013 Gateway Developer Guide and Reference

Testing Transactions

Processors Other Than PayPal

Processing Platform RESULT Values Available for Testing

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

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

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

Global Payments Central 0, 4, 5, 8, 12, 13, 23, 24, 104, 111, 114, 1000

Global Payments East 0, 4, 5, 12, 13, 23, 24, 30, 100, 104, 114, 1000

Paymentech Salem (New Hampshire) 0, 12, 13, 104

Paymentech Tampa 0, 3, 4, 5, 12, 13, 23, 24, 1000

TSYS Acquiring Solutions 0, 4, 12, 13, 23, 104, 114, 1000

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

Result Values Based On Alternate Generation Methods

The following table shows another method for obtaining RESULT values. Servers do not return non-zero RESULT values from processors. Therefore, you cannot simulate non-zero RESULT values using the amount. In some cases, you may obtain certain results using the RESULT value plus 1000 even though this table suggests an alternate means of obtaining the RESULT value.

RESULT value Definition How to test using Payflow Gateway

0 Approved Use an AMOUNT of $1000 or less

For all processors except Global Payments Central (MAPP) and FDI

Credit (C) and force (F) transactions will always be approved regardless of dollar amount or card number

1 User authentication failed Use an invalid PWD

2 Invalid tender Use an invalid TENDER, such as G

3 Invalid transaction type Use an invalid TRXTYPE, such as G

4 Invalid amount Use an invalid AMOUNT, such as –1

5 Invalid merchant information Use the AMOUNT 1005 - Applies only to the following

processors: Global Payments East and Central, and American Express

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

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

13 Referral Use the AMOUNT 1013

Gateway Developer Guide and Reference 07 February 2013 87

Testing Transactions

Processors Other Than PayPal

RESULT value Definition How to test using Payflow Gateway

19 Original transaction ID not

found

22 Invalid ABA number Applies only to ACH transactions – submit an invalid

23 Invalid account number Submit an invalid account number, for example,

24 Invalid expiration date Submit an invalid expiration date, for example, 0298

25 Transaction type not mapped to

this host (Processor)

29 Invalid XML document Pass a bad XML document (XMLPay users only)

30 Duplicate Transaction Use the AMOUNT 1030 - Only applies to Global

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

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

100 Invalid transaction returned

from host (Processor)

Submit a delayed capture transaction with an invalid

ORIGID

ABA number (8 digits)

000000000000000

Submit a transaction for a card or tender you are not currently set up to accept, for example, a Diners card if you aren’t set up to accept Diners

Payments East and Global Payments Central processors

Payments East

Use the AMOUNT 1100 - Only applies to Global Payments East and Central

101 Time-out value too small Set timeout value to 1

103 Error reading response from

host (Processor)

104 Timeout waiting for processor

response

105 Credit error Attempt to credit an authorization

108 Void error Attempt to void a captured authorization

111 Capture error Capture an authorization transaction twice or attempt

112 Failed AVS check You cannot generate this RESULT value by

113 Cannot exceed sales cap Applies to ACH transactions only

Use the AMOUNT 1103

Use the AMOUNT 1104

to capture a transaction that is not an authorization transaction

submitting an amount of 1112, but must submit a value for Address Verification Service that will fail; in production, this error occurs only if your account is configured by PayPal customer service to use the “AVS Deny” feature

88 07 February 2013 Gateway Developer Guide and Reference

Testing Transactions

Processors Other Than PayPal

RESULT value Definition How to test using Payflow Gateway

114 CVV2 Mismatch Use the AMOUNT 1114. Only applies to TSYS

Acquiring Solutions, Merchant e-Solutions, and Global Payments East and Global Payments Central processors

1000 Generic Host (Processor) Error Use the AMOUNT 2000 - Does not apply to Elavon

(formerly Nova), American Express, or Global Payments East processors

Testing Address Verification Service

The Payflow testing server simulates address verification service by returning a value for AVSADDR based on the first 3 characters of the submitted value for BILLTOSTREET.

The testing server returns a value for AVSZIP based on the submitted BILLTOZIP value as shown in the table.

If BILLTOSTREET starts with 667 or higher or begins with a non-numeric character, then the simulator returns AVSADDR=X, AVSZIP=X.

The following table tests AVSADDR.

Submitted Value for BILLTOSTREET

000-333 24285 Elm Y

334-666 49354 Main N

667 or higher or begins with a non-

numeric character

Example BILLTOSTREET Value AVSADDR Result

79232 Maple X

The following table tests AVSZIP.

Submitted Value for BILLTOZIP Example BILLTOZIP Value AVSZIP Result

00000-50000 00382 Y

50001-99999 94303 N

Any value (if street address is 667 or higher or begins with a non-numeric character)

BILLTOSTREET=79232 Maple, BILLTOZIP=20304

Gateway Developer Guide and Reference 07 February 2013 89

Testing Transactions

PayPal Processor

Testing Card Security Code

If you submit a value for the card security code, the cardholder’s bank returns a Yes / No / Not Supported (Y / N / X) response on whether the value matches the number on file at the bank. Card security code is described in “Card Security Code Validation”.

NOTE: Some processors will decline (RESULT value 12) a transaction if the card

security code does not match without returning a CVV2MATCH value. Test the results and check with your processor to determine whether they support card security code checking.

For the testing server, the first three characters of the CVV2 value determine the CVV2MATCH result, as shown here.

Testing CVV2MATCH

CVV2 Value CVV2MATCH Value

000 Y

001-300 Y

301-600 N

601 or higher X

PayPal Processor

For the PayPal processor, use the following guidelines.

Credit Card Numbers for Testing

For the PayPal processor, use the following credit card numbers for testing. Any other card number produces a general failure.

American Express 378282246310005

American Express 371449635398431

Amex Corporate 378734493671000

Australian BankCard 5610591081018250

Diners Club 30569309025904

Diners Club 38520000023237

Discover 6011111111111117

Discover 6011000990139424

90 07 February 2013 Gateway Developer Guide and Reference

JCB 3530111333300000

JCB 3566002020360505

MasterCard 5555555555554444

MasterCard 5105105105105100

Vis a 4111111111111111

Vis a 4012888888881881

Vis a 4222222222222

NOTE: Even though this number has a different character

count than the other test numbers, it is the correct and functional number.

Result Values Based On Amount

The following table shows another method for obtaining RESULT values. The servers do not return non-zero RESULT values from processors.Therefore you cannot simulate non-zero

RESULT values using the amount. In some cases, you may obtain certain results using the RESULT value plus 1000 even though this table suggests another means of obtaining the RESULT value.

Testing Transactions

PayPal Processor

Result Definition How to test

0 Approved Use an AMOUNT of 10000 or less

3 Invalid transaction type Use the AMOUNT 10402

4 Invalid amount Use any of these as AMOUNT:

 10400  10401  10403  10404

5 Invalid merchant information Use any of these as AMOUNT:

 10548  10549

Gateway Developer Guide and Reference 07 February 2013 91

Testing Transactions

PayPal Processor

Result Definition How to test

7 Field format error Use any of these as AMOUNT:

 10405  10406  10407  10408  10409  10410  10412  10413  10416  10419  10420  10421  10509  10512  10513  10514  10515  10516  10517  10518  10540  10542

12 Declined Use any of these as AMOUNT:

 10417  15002  15005  15006  15028  15039  10544  10545  10546

13 Referral Use the AMOUNT 10422

23 Invalid account number Use any of these as AMOUNT:

 10519  10521  10522  10527  10535  10541  10543

92 07 February 2013 Gateway Developer Guide and Reference

Testing Transactions

PayPal Processor

Result Definition How to test

24 Invalid expiration date Use any of these as AMOUNT:

 10502  10508

30 Duplicate Transaction Use the AMOUNT 10536

105 Credit error Attempt to credit an authorization

112 Failed AVS check Use the AMOUNT 10505

114 CVV2 Mismatch Use the AMOUNT 10504

1000 Generic Host (Processor) Error Use an AMOUNT other than those listed in this column

Gateway Developer Guide and Reference 07 February 2013 93

Testing Transactions

PayPal Processor

94 07 February 2013 Gateway Developer Guide and Reference

Transaction Responses

When a transaction finishes, the Payflow server returns a response string made up of namevalue pairs. The following is an example response string:

RESULT=0&PNREF=EFHP0D426A53&RESPMSG=APPROVED&AUTHCODE=25TEST&AVSADDR=Y&AVSZ IP=N&CVV2MATCH=Y

Credit Card Transaction Responses

The table below describes values that can be returned in response strings.

Field Description

PNREF Gateway transaction ID, a unique number that identifies the transaction.

Character length and limitations: 12 alphanumeric characters

PPREF Unique transaction ID of the payment.

Character length and limitations: 17-character string

RESULT The outcome of the attempted transaction. RESULT=0 means the transaction was

approved.

NOTE: For account verification transactions, RESULT=0 with RESPMSG=Verified

means a zero dollar authorization has been successfully performed.

NOTE: The PayPal processor may also return a warning message in the RESPMSG

string when RESULT=0. For more information on corrective actions, see the PayPal developer documentation on the PayPal developer website.

Any other value for RESULT indicates a decline or error. Character length and limitations: variable length, numeric

CVV2MATCH Result of the card security code (CVV2) check. The issuing bank may decline the

transaction if there is a mismatch. In other cases, the transaction may be approved despite a mismatch.

Character length and limitations: 1 alpha character (Y, N, X, or no response)

Gateway Developer Guide and Reference 07 February 2013 95

Transaction Responses

Credit Card Transaction Responses

Field Description

RESPMSG The response message returned with the transaction result. Exact wording varies.

Sometimes a colon appears after the initial RESPMSG followed by more detailed information.

NOTE: For account verification transactions, RESULT=0 with RESPMSG=Verified

means a zero dollar authorization has been successfully performed.

NOTE: The PayPal processor may also return a warning message in the RESPMSG

string when RESULT=0. For more information on corrective actions, see the PayPal developer documentation on the PayPal developer website.

NOTE: For partial authorizations, RESPMSG=Partial Approval when

RESULT=0.

Character length and limitations: variable, alphanumeric characters

AUTHCODE Returned for sale, authorization, and voice authorization credit card transactions.

AUTHCODE is the approval code obtained over the telephone from the processing

network. AUTHCODE is required when submitting a force (F) transaction. Character length and limitations: 6 alphanumeric characters

AVSADDR Address verification service address response returned if you are using address

verification service. Address verification service address responses are for advice only. This process does not affect the outcome of the authorization.

Character length and limitations: 1 alpha character (Y, N, X, or no response)

AVSZIP Address verification service address response returned if you are using address

verification service. Address verification service address responses are for advice only. This process does not affect the outcome of the authorization.

Character length and limitations: 1 alpha character (Y, N, X, or no response)

IAVS International address verification service address responses may be returned if you

are using Address verification service. IAVS responses are for advice only. This value does not affect the outcome of the transaction.

Indicates whether address verification service response is international (Y), US (N), or cannot be determined (X). Client version 3.06 or later is required.

Character length and limitations: 1 alpha character (Y, N, X, or no response)

PROCAVS The raw address verification service response returned by the processor. This field is

not normalized and is returned when VERBOSITY is set to HIGH. Character length and limitations: 1 character

PROCCVV2 The raw CVV2 response returned by the processor. This field is not normalized and is

returned when VERBOSITY is set to HIGH. Character length and limitations: 1 character

96 07 February 2013 Gateway Developer Guide and Reference

Transaction Responses

Credit Card Transaction Responses

Field Description

HOSTCODE The raw response code returned by the processor. This field is not normalized and is

returned when VERBOSITY is set to HIGH. Use RESPTEXT to obtain the response message from the processor. For additional PayPal processor response code information, refer to the PayPal API error codes contact your merchant bank or processor directly.

Character length and limitations: 6 characters

RESPTEXT The raw text returned by the processor which corresponds to the returned

HOSTCODE. This field is not normalized and is returned when VERBOSITY is set to HIGH.

Character length and limitations: 32 characters

PROCCARDSECURE The raw Buyer Authentication response returned by the processor. This field is not

normalized and is returned when VERBOSITY is set to HIGH. Character length and limitations: 1 character

ADDLMSGS Additional error message that indicates the use of a features that has been disabled.

Character length and limitations: Up to 1048 characters. Typically 50 characters.

. For all other processors, please

PAYMENTTYPE (PayPal only.) Returns instant if the payment is instant or echeck if the payment

is delayed (DP) on the PayPal processor. Character length and limitations: 7-character string

CORRELATIONID (PayPal only.) Value used for tracking this Direct Payment transaction.

Character length and limitations: 13 alphanumeric characters

AMEXID Unique transaction ID returned when VERBOSITY=HIGH for tracking American

Express CAPN transactions on non-PayPal processors.

NOTE: Used by merchants who authorize transactions through the Gateway but settle

through a third-party solution.

Character length and limitations: 15 numeric characters

AMEXPOSDATA Value returned for American Express CAPN transactions when VERBOSITY=HIGH

on non-PayPal processors.

NOTE: Used only by merchants who authorize through the Gateway but settle

through a third-party solution.

Character length and limitations: 12 alphanumeric characters

AMT This field returns the transaction amount or if performing a partial authorization it

will return the amount approved for the partial authorization.

ORIGAMT Partial authorizations: Original amount submitted for authorization.

Gateway Developer Guide and Reference 07 February 2013 97

Transaction Responses

Address Verification Service Responses From PayPal

Field Description

CARDTYPE The credit card type. Is returned in an inquiry response when you send a VERBOSITY

request parameter value of HIGH. Is one of the following values for currently used cards:

 0 = Visa  1 = MasterCard  2 = Discover  3 = American Express  4 = Diner’s Club  5 = JCB

EMAILMATCH Verifies whether the BILLTOEMAIL value sent is what is on file with the processor.

(American Express processor only) Character length and limitations: 1 alpha character (Y, N, X, or no response)

PHONEMATCH Verifies whether the BILLTOPHONENUM value sent is what is on file with the

processor. (American Express processor only) Character length and limitations: 1 alpha character (Y, N, X, or no response)

EXTRSPMSG Additional processor-related messages.

TRANSTIME Time of the transaction. The following is an example response in the format returned:

TRANSTIME=2010-08-11 22:53:18

Character length and limitations: See example

DUPLICATE Is returned with one of the following values:

 DUPLICATE=2 — ORDERID has already been submitted in a previous request

with the same ORDERID.

 DUPLICATE=1 — The request ID has already been submitted for a previous

request.

 DUPLICATE=-1 — The Gateway database is not available. PayPal cannot

determine whether this is a duplicate order or request.

DATE_TO_SETTLE The date a transaction will settle. This parameter is returned in the response for

inquiry transactions only (TRXTYPE=I).

Address Verification Service Responses From PayPal

The following table compares the detailed response the PayPal processor returns for address verification to the normalized response value (Y, N, or X) that AVSADDR and AVSZIP return. To obtain the PayPal processor value, set the VERBOSITY parameter to HIGH. The processor value is returned in the PROCAVS response parameter.

98 07 February 2013 Gateway Developer Guide and Reference

Transaction Responses

Address Verification Service Responses From PayPal

PayPal processor AVS code Meaning AVSADDR AVSZIP

AAddress YN

B International “A” Y N

C International “N” N N

D International “X” Y Y

E Not allowed for MOTO (Internet/Phone)

transactions

F UK-specific “X” Y Y

G Global Unavailable X X

I International Unavailable X X

NNo NN

P Postal (International “Z”) N Y

RRetry XX

S Service not Supported X X

U Unavailable X X

WWhole Zip N Y

X Exact Match Y Y

YYes YY

ZZip NY

All other X X

The following is an example Authorization request string that sets VERBOSITY to HIGH. Payflow returns the PROCAVS value in the response.

TRXTYPE=A&BILLTOSTREET=123 Main St&BILLTOZIP=00382&TENDER=C&PARTNER=PayPal& USER=SuperMerchant&PWD=SuperUserPassword&AMT=1.00&ACCT=4111111111111111&EXP DATE=1215&INVNUM=PONUM1&VERBOSITY=HIGH

The PROCAVS value is returned in the response.

RESULT=0&PNREF=VFHA0FF94691&RESPMSG=Approved&AUTHCODE=245PNI&AVSADDR=Y&AVSZ IP=Y&HOSTCODE=A&PROCAVS=Y&VISACARDLEVEL=12&TRANSTIME=2011-01-12 13:54:35&AMT=1.00&ACCT=1111&EXPDATE=1215&CARDTYPE=0&IAVS=N

Gateway Developer Guide and Reference 07 February 2013 99

Transaction Responses

Card Security Code Results

Normalized Card Security Code Results

The CVV2MATCH parameter returns Y, N, or X or a processor-specific response.

The CVV2MATCH parameter returns Y, N, or X.

The following table shows the detailed results that the PayPal processor returns for card security codes. To obtain the PayPal processor value, set the VERBOSITY parameter to HIGH. The processor value is returned in the PROCCVV2 response parameter.

PayPal Processor Code

PayPal Processor CVV2 Code

M Match Y

NNo MatchN

Description PROCVV2MATCH

P Not Processed X

S Service Not Supported X

U Unavailable X

X No Response X

All other X

PayPal Card Security Code Results

The following table shows the detailed results the PayPal processor returnes for card security codes. To obtain the PayPal processor value, set the VERBOSITY parameter to HIGH. The processor value is returned in the PROCCVV2 response parameter.

PayPal Processor Code

PayPal Processor CVV2 Code

M Match Y

NNo MatchN

P Not Processed X

Description PROCVV2MATCH

S Service Not Supported X

U Unavailable X

X No Response X

100 07 February 2013 Gateway Developer Guide and Reference

PayPal Gateway - 2013 Developer's Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Content

Scope

Preface

Related Documentation

Intended Audience

Who Should Use This Document

Revision History

About the Gateway Checkout Solutions

Summary of the Gateway Checkout Solutions

Gateway Product Details

About the Gateway Transaction Flow

About Security

Secure Token

Hosted Checkout Pages

PCI Compliance Without Hosted Pages: Transparent Redirect

Processing Platforms Supporting Card-Present Transactions

Supported Payment Types

Supported Languages

Recurring Billing Service

Fraud Protection Service

Secure Token

About the Secure Token

Integrating the Secure Token With the Hosted Checkout Pages

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

Secure Token Errors

Posting To the Hosted Checkout Page

Configuring Hosted Checkout Pages

Configuring Hosted Pages Using PayPal Manager

Setup

Customize

Using a Secure Token to Pass Hosted Pages Customization Parameters

Integrate

Using the PARMLIST Parameter

Hosted Pages and Mobile Browsers

Mobile Optimized Checkout Pages

Silent Posts

Force Silent Post Confirmation

Passing Other Data to Your Server Using Post or Silent Post

Data Returned by the Silent Post Features

Payflow SDK

Preparing the Payflow Gateway Client Application

Activating Your Payflow Gateway Account

Host URL Addresses

About Name-Value Pairs

Using Special Characters In Values

Payflow Connection Parameters

Name-Value Parameter Syntax Guidelines

Do Not URL Encode Name-Value Parameter Data

User Parameter Data

Sale Transaction Example

Typical Sale Transaction

Formatting Payflow Gateway Transactions

Submitting Credit Card Transactions

Obtaining an Internet Merchant Account

About Credit Card Processing

Credit Card Features

Planning Your Gateway Integration

Complying With E-commerce Indicator

Handling Credit Card Type Information

Core Credit Card Parameters

Submitting Account Verifications

When To Use Account Verifications

Required Account Verification Parameters

Submitting Authorization/Delayed Capture Transactions

Example Account Verification String

When to Use Authorization/Delayed Capture Transactions

Submitting Balance Inquiry Transactions

Required Authorization Transaction Parameters

Typical Authorization Transaction Parameter String

Submitting Card Present (SWIPE) Transactions

Processing Platforms Supporting Balance Inquiry Transactions

Required Balance Inquiry Parameters

Example Balance Inquiry Transaction String

Processing Platforms Supporting Card-Present Transactions

Card Present Transaction Syntax

Submitting Credit Transactions