PayPal Gateway - 2012 Developer's Guide

Gateway Developer

Guide and Reference

PayPal Payments Advanced

PayPal Payments Pro

Payflow Pro

Payflow Link

Last updated: 31 July 2012

Gateway Developer Guide and Reference

Document Number: 200045.en_US-20120731

© 2012 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 P Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Who Should Use This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

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

About the Gateway Checkout Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Summary of the Gateway Checkout Solutions . . . . . . . . . . . . . . . . . . . . . 19

Gateway Product Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

About the Gateway Transaction Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

About Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Secure Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Hosted Checkout Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

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

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

Supported Payment Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Recurring Billing Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Chapter 2 Secure Token . . . . . . . . . . . . . . . . . . . . . . . . 27

About the Secure Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

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

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

Posting To the Hosted Checkout Page . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Chapter 3 Configuring Hosted Checkout Pages . . . . . . . . . . . . 31

Configuring Hosted Checkout Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Configuring Hosted Pages Using PayPal Manager . . . . . . . . . . . . . . . . . . . . . 31

Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Customize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Gateway Developer Guide and Reference 31 July 2012 3

Content

4

Using a Secure Token and Dynamically Passing Form Post Variables . . . . . . . . . . . 36

Silent Posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Force Silent Post Confirmation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

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

Chapter 4 Payflow SDK . . . . . . . . . . . . . . . . . . . . . . . . . 41

Preparing the Payflow Gateway Client Application . . . . . . . . . . . . . . . . . . . . . 41

Activating Your Payflow Gateway Account. . . . . . . . . . . . . . . . . . . . . . . . . . 42

Host URL Addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

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

About Name-Value Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Using Special Characters In Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Name-Value Parameter Syntax Guidelines . . . . . . . . . . . . . . . . . . . . . . . 44

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

Payflow Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

User Parameter Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Sale Transaction Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Typical Sale Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Formatting Payflow Gateway Transactions . . . . . . . . . . . . . . . . . . . . . . . . . 46

Chapter 6 Submitting Credit Card Transactions . . . . . . . . . . . . 47

Obtaining an Internet Merchant Account. . . . . . . . . . . . . . . . . . . . . . . . . . . 47

About Credit Card Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Credit Card Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Planning Your Gateway Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Complying With E-commerce Indicator . . . . . . . . . . . . . . . . . . . . . . . . . 50

Handling Credit Card Type Information . . . . . . . . . . . . . . . . . . . . . . . . . 50

Core Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Submitting Account Verifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

When To Use Account Verifications . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Required Account Verification Parameters . . . . . . . . . . . . . . . . . . . . . . . 54

Example Account Verification String . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Submitting Authorization/Delayed Capture Transactions . . . . . . . . . . . . . . . . . . 55

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

Required Authorization Transaction Parameters . . . . . . . . . . . . . . . . . . . . 56

Typical Authorization Transaction Parameter String . . . . . . . . . . . . . . . . . . . 56

31 July 2012 Gateway Developer Guide and Reference

Content

Submitting Balance Inquiry Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Processing Platforms Supporting Balance Inquiry Transactions . . . . . . . . . . . . 56

Required Balance Inquiry Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Example Balance Inquiry Transaction String . . . . . . . . . . . . . . . . . . . . . . 57

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

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

Card Present Transaction Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Submitting Credit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Required Credit Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . 59

Submitting Inquiry Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

When To Use an Inquiry Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Required Parameters When Using the PNREF . . . . . . . . . . . . . . . . . . . . . 61

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

Required Parameters When Using the CUSTREF . . . . . . . . . . . . . . . . . . . 62

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

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

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

Submitting Partial Authorizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

When To Use Partial Authorizations . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Required Partial Authorization Parameters . . . . . . . . . . . . . . . . . . . . . . . 64

Example Partial Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Submitting Purchasing Card Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Submitting Reference Transactions (Tokenization) . . . . . . . . . . . . . . . . . . . . . 66

When To Use a Reference Transaction . . . . . . . . . . . . . . . . . . . . . . . . . 66

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

Fields Copied From Reference Transactions . . . . . . . . . . . . . . . . . . . . . . 67

Example Reference Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

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

Submitting Sale Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

When To Use a Sale Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Additional Parameters For Sale Transactions . . . . . . . . . . . . . . . . . . . . . . 69

Typical Sale Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . . 69

Submitting Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

About Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Ways to Send Soft Merchant Information . . . . . . . . . . . . . . . . . . . . . . . . 70

Submitting Voice Authorization Transactions . . . . . . . . . . . . . . . . . . . . . . . . 71

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

Required Voice Authorization Transaction Parameters . . . . . . . . . . . . . . . . . 72

Submitting Void Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72


Content

6

When To Use a Void Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Required Void Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 73

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

Example Void Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . 74

Using Address Verification Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Example Address Verification Service Parameter String . . . . . . . . . . . . . . . . 74

Using Card Security Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Chapter 7 Testing Transactions . . . . . . . . . . . . . . . . . . . . 77

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

Testing Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Processors Other Than PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Credit Card Numbers for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Testing Address Verification Service. . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Testing Card Security Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

PayPal Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Credit Card Numbers for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Result Values Based On Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Chapter 8 Transaction Responses . . . . . . . . . . . . . . . . . . . 87

Credit Card Transaction Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Address Verification Service Responses From PayPal . . . . . . . . . . . . . . . . . . . 90

Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Normalized Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . 92

PayPal Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

BALAMT Response and Stored Value Cards . . . . . . . . . . . . . . . . . . . . . . . . 93

American Express Stored Value Card Example . . . . . . . . . . . . . . . . . . . . . 93

PNREF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

RESULT Values and RESPMSG Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

RESULT Values For Communications Errors . . . . . . . . . . . . . . . . . . . . . .100

Chapter A Processors Requiring Additional Transaction Parameters 103

American Express Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . .103

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

Internet Transaction Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104

Address Verification Service Parameters . . . . . . . . . . . . . . . . . . . . . . . .105

Location Transaction Advice Addendum Parameters . . . . . . . . . . . . . . . . . .105


Content

Transaction Advice Detail Parameters. . . . . . . . . . . . . . . . . . . . . . . . . .107

Airline Passenger Data Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .107

American Express Other Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .108

Elavon Additional Credit Card Parameters. . . . . . . . . . . . . . . . . . . . . . . . . .109

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

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

Heartland, Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . 111

Litle Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

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

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

Express . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113

Internet Transaction Data Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .113

AVS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114

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

PayPal Credit Card Transaction Request Parameters . . . . . . . . . . . . . . . . . . . .115

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

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

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

AVS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121

Location Transaction Advice Addendum Parameters . . . . . . . . . . . . . . . . . .122

Transaction Advice Detail Parameters. . . . . . . . . . . . . . . . . . . . . . . . . .123

Airline Passenger Data Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .123

Other Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125

Vantiv Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .125

Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .125

Soft Merchant Descriptor Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .126

WorldPay Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . .127

Chapter B TeleCheck Electronic Check Processing . . . . . . . . . 129

TeleCheck NFTF Overview of Services . . . . . . . . . . . . . . . . . . . . . . . . . . .129

TeleCheck NFTF Processing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . .129

NFTF Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129

NFTF Processing Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . .131

NFTF Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131

TeleCheck Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132

Required TeleCheck Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .133

Testing TeleCheck Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135

Example Test Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135


Content

8

Preparing for TeleCheck Production Transactions . . . . . . . . . . . . . . . . . . . . . .136

Responses to TeleCheck Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . .136

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

Response Code Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137

Sale Response Code Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137

Adjustment Code Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138

Response Codes For Status Response Packets . . . . . . . . . . . . . . . . . . . .138

TeleCheck Authorization Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . .139

Authorization – Sales Consent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139

Authorization – Sales Decline/Error . . . . . . . . . . . . . . . . . . . . . . . . . . .142

Chapter C Submitting Purchasing Card Level 2 and Level 3 Transactions

143

About Purchasing Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143

About Program Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143

Accepted BIN Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144

About American Express Purchasing Card Transactions . . . . . . . . . . . . . . . . . .144

Supported Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144

Avoiding Downgrade. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145

Submitting Successful Level 3 Transactions . . . . . . . . . . . . . . . . . . . . . .145

Edit Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145

Accepted BIN Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

American Express Purchasing Card Transaction Processing . . . . . . . . . . . . . . . .146

American Express Level 2 Parameters for American Express . . . . . . . . . . . . .146

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

American Express Level 3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . .149

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

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

Elavon Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152

Elavon Additional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152

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

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

FDMS Nashville Commercial Card Parameters . . . . . . . . . . . . . . . . . . . . .153

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

FDMS North Purchasing Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .154

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

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

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

FDMS South Line Item Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .157


Content

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

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

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

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

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

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

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

160

Heartland Purchasing Card Transaction Processing. . . . . . . . . . . . . . . . . . . . .160

Heartland Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160

Heartland Level 3 MasterCard Parameters . . . . . . . . . . . . . . . . . . . . . . .161

Heartland Level 3 Visa Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .163

Litle Purchasing Card Transaction Processing. . . . . . . . . . . . . . . . . . . . . . . .166

Litle Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166

Litle Level 3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167

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

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

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

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

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

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

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

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

Paymentech Tampa Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . .181

Example Paymentech Tampa Level 2 Visa and MasterCard Transaction Parameter String

181

SecureNet Purchasing Card Transaction Processing . . . . . . . . . . . . . . . . . . . .181

SecureNet Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181

SecureNet Level 3 MasterCard Parameters . . . . . . . . . . . . . . . . . . . . . . .182

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

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

TSYS Acquiring Solutions Level 2 Parameters . . . . . . . . . . . . . . . . . . . . .187

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

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

Vantiv Purchasing Card Transaction Processing . . . . . . . . . . . . . . . . . . . . . .193

Vantiv Purchasing Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193

Vantiv Purchasing Card Line Item Parameters . . . . . . . . . . . . . . . . . . . . .193

WorldPay Purchasing Cards Transaction Processing . . . . . . . . . . . . . . . . . . . .194

WorldPay Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194

WorldPay Level 3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196


Content

Chapter D VERBOSITY: Viewing Processor-Specific Transaction Results

199

Chapter E ISO Country Codes . . . . . . . . . . . . . . . . . . . . 201

Chapter F Codes Used by FDMS South Only . . . . . . . . . . . . . 203

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

Visa Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .210

Units of Measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217

Chapter G PayPal Acquirer . . . . . . . . . . . . . . . . . . . . . . 225

Countries and Regions Supported by PayPal . . . . . . . . . . . . . . . . . . . . . . . .225

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225

PayPal Currency Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225

Chapter H Additional Processor Information . . . . . . . . . . . . . 227

Moneris Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227

Chapter I Payflow Link Migration . . . . . . . . . . . . . . . . . . 229

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

10 31 July 2012 Gateway Developer Guide and Reference

P

Preface

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

Scope

This guide is a reference to the payment card data parameters available for submitting in transaction requests over the Gateway to multiple supported processors. It also covers the resulting response data parameters and errors.

The guide describes the requirements of an ever growing list of processing platforms. It organizes parameters into a core set of request parameters supported by all processors, additional parameters unique to individual processors, and purchasing card parameters specialized to monitor credit card use in businesses. It also provides a section on response parameters and error codes (PNREF values that are not 0).

Although this guide provides guidance on getting started with the SDK, setting up credit card processing, and testing your integration, its broad scope does not lend to use as a tutorial on integration. Refer to the PayPal Developer website and the Payflow Gateway SDK for detailed working examples and use cases.

Related Documentation

For additional information on the Gateway payments solutions:



See PayPal Manager at:

 https://manager.paypal.com/

For more information on Payflow documentation, examples, and very current information, see the PayPal developer site at the following URL: https://www.x.com/developers/paypal

Intended Audience

This guide provides Gateway payments solutions to readers who:



Are web or application developers



Have a background in payments services


12

P

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 Payflow Link User’s Guide . Additionally, all the Gateway features explained in this guide are not necessarily available to every Gateway customer. This section will help you determine whether you should use this document and which sections of the document are relevant to you.

To view the Gateway solutions available to you, login to PayPal Manager at https://manager.paypal.com/ . PayPal Manager displays your Gateway Services in the Service

Summary box.



Payflow Link

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

A) Legacy Payflow Link users will see the following in the Service Summary box in PayPal

Manager:

Payflow Link

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

User’s Guide .

B) New Payflow Link users will see the following in the Service Summary box in PayPal

Manager:

Hosted Checkout Pages & Payflow SDK/API (Limited Access). (If PayPal Payments

Advanced is also listed, then you are not a Payflow Link customer).


Preface

Intended Audience

P

New Payflow Link users who are using the Secure Token or the API should use this guide.

However, new Payflow Link users who are using the legacy Payflow Link input tag integration should use the Payflow Link User’s Guide instead.

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

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

Hosted Checkout Pages.



Payflow Pro

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

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

Manager:

Payflow Pro

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

Payflow Pro user, you should skip the chapter on Hosted Checkout Pages -

“Configuring

Hosted Checkout Pages” on page 31

.

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)


14

P

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)


Preface

Revision History

P

Revision History

Revision History for the Gateway Developer Guide and Reference:

Date

31 July 2012

23 July 2012

16 July 2012

June 2012

May 2012

Description

Added a list of Setup Params and

Customize Params .

These parameters override PayPal Manager settings for

Hosted Pages.

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.

Added the Bill Me Later feature to the

Gateway Product

Details section.

Updated required value for BILLTOCITY,

BILLTOSTATE & BILLTOCOUNTRY

in

PayPal Credit

Card Transaction Request Parameters table.

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

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


16

P

Preface

Revision History

Date

May 2012 (cont.)

April 2012

January 2012

Description

Document maintenance: Added cross-references and external links; reorganized content; removed no longer applicable content.

Added new transaction type:

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

Updated TeleCheck chapter:

Updated MICR values in Testing TeleCheck

Transactions section

Added TeleCheck Adjustment Response Code Values table

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

Updated processor and entity names:

Vantiv, previously known as Fifth Third Processing

Solutions

PayPal Australia, previously known as First Data

Australia

Added new processors:

First Third International

Heartland Payment Systems

Planet Payment

SecureNet

TeleCheck

WorldPay

Added new transaction types:

TRXTYPE=L

can be used to upload credit card data, easing PCI compliance. You can store the resulting

PNREF

locally for use in performing reference transactions.


Date

January 2012 (cont.)


Description

Added request NVPs:

ADDLAMT n

ADDLAMTTYPE n

AUTHDATE

CATTYPE

CONTACTLESS

CUSTDATA

CUSTOMERID

CUSTOMERNUMBER

DISCOUNT

DUTYAMT

DLNAME

DLNUM

DOB

L_ALTTAXAMT n

L_ALTTAXID n

L_ALTTAXRATE n

L_CARRIERSERVICELEVELCODE n

L_COMMCODE n

L_EXTAMT n

L_PRODCODE n

L_TAXTYPE n

ORDERID

MERCHANTDESCR

MERCHANTINVNUM

MERCHANTNAME

MERCHANTURL

MERCHANTVATNUM

MERCHANTZIP

MISCDATA

REPORTGROUP

SILENTTRAN

STREET3

VATINVNUM

VATTAXAMT

VATTAXRATE

Added response NVPs:

DUPLICATE

(response)

EXTRMSG

(response)

Preface

Revision History

P

31 July 2012 17

P

Preface

Revision History

Date

January 2012 (cont.)

February 2011

Description

Added concepts:

Gateway Product Solutions - PayPal Payments

Advanced, PayPal Payments Pro, Payflow Pro, Payflow

Link

Transaction Flow

Transparent Redirect

First publication.


1

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 19

“About the Gateway Transaction Flow” on page 21









“About Security” on page 22

“Processing Platforms Supporting Card-Present Transactions” on page 24

“Supported Payment Types” on page 25

“Recurring Billing Service” on page 26

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


20

1

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.

Feature

Hosted checkout page (including an iFrame version)

PayPal payments

Bill Me Later payments

(Available to US merchants only on

Hosted checkout pages.)

Included

PayPal branding on full page templates Yes

Transparent Redirect

Supports PayPal as a processor and an acquirer

Credit and debit cards

Level 2 and Level 3 purchase cards


Payflow Link

Yes

Included

No

Yes

Yes

Yes

No TeleCheck (guaranteed electronic checks)

ACH (electronic checks)

Virtual Terminal support, including card-present data passage

Virtual Terminal

API

No

Yes

Payflow Link only

Limited access (no authorization or sale)


Payflow Pro

Yes

Optional

Optional

Optional

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Full access



About the Gateway Transaction Flow

1

Feature


Payflow Link

Reference transactions (Tokenization) Yes

Secure token to preset hosted checkout page

Yes

Reporting APIs

Desktop integration

Recurring billing

Basic fraud protection

Advanced fraud protection

Partner/channel distribution support

(Partner Manager, registration, XML registration) resale and referral

Yes

Yes

Yes

Yes

Yes

Yes


Payflow Pro

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

About the Gateway Transaction Flow

The traditional transaction flow is as follows. Numbers correspond to numbers in the figure.

1. At your website, the customer clicks Buy to purchase merchandise.

2. You send the transaction request to the Gateway server.

3. The Gateway sends the transaction to the payment processing network.

4. Your processor sends the response back to the Gateway server and processes the transaction (obtains the payment from the customer bank and deposits it in the merchant bank).

5. The Gateway server returns the response to your website.

6. Your website displays the result to the customer.


1


About Security

22

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:



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.



About Security

1

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.

Numbers in the figure correspond to the numbered comments below:

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

2. You request a secure token by passing a token ID to the Gateway server.

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

4. You submit the secure token and token ID in an HTTP post to pages hosted on the Gateway server and redirect the customer’s browser to the hosted pages.

5. The Gateway server uses the secure token to retrieve the amount and other transaction data.

The customer submits their credit card number, expiration date, and other sensitive data directly to the host pages rather than to your website, easing your PCI compliance requirements.


24

1


Processing Platforms Supporting Card-Present Transactions

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 61

.

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.

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.



Supported Payment Types

1

American Express

American Express APAC

Elavon

Fifth Third Processing Solutions

First Data Merchant Services (FDMS) Nashville

First Data Merchant Services (FDMS) North

First Data Merchant Services (FDMS) South

Global Payments Central

Global Payments East


Litle

Merchant e-Solutions

Moneris Solutions

Paymentech Salem

Paymentech Tampa

PayPal

SecureNet

TeleCheck

TSYS Acquiring Solutions

WorldPay

Supported Payment Types

Credit cards

PayPal (supported by PayPal’s Express Checkout product)

Pinless debit cards

Electronic checks

Check cards

Purchasing cards (also referred to as commercial cards, corporate cards, procurement cards, or business cards)

Level 2 and Level 3


1


Recurring Billing Service

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

Representative.

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. Using the Gateway to define and manage recurring transactions programmatically is described in Payflow Pro – Recurring Billing

Service User’s Guide . You can manage Recurring Billing tasks in PayPal Manager .


2

Secure Token

This section describes the secure token.



“Secure Token” on page 27







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

“Integrating the Secure Token Without the Hosted Checkout Pages: Transparent Redirect” on page 28

“Posting To the Hosted Checkout Page” on page 29

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 47

.

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


2

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

28

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 47

.

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


Secure Token

Posting To the Hosted Checkout Page

2

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

CREATESECURETOKEN=Y

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

SILENTTRAN=TRUE

Transparent Redirect Example

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

TRXTYPE=A&BILLTOSTREET=123 Main St.&BILLTOZIP=95131&AMT=24.35&INVNUM=INV123

45&PONUM=PO12345&CURRENCY=USD&CREATESECURETOKEN=Y&SECURETOKENID=9a9ea8208de

1413abc3d60c86cb1f4c5&SILENTTRAN=TRUE

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

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

OKENID =9a9ea8208de1413abc3d60c86cb1f4c5

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

NOTE

: It is highly recommended that you add scripting to ensure the the browser posts the sensitive data directly to the PayPal Gateway server rather than to your website.

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.


30

2

Secure Token

Posting To the Hosted Checkout Page

<html>

<META http-equiv="Content-Type" content="text/html; charset=UTF-8">

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

</center>

</body>

</html>

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

“Sending a Simple

Transaction to the Server” on page 43 .

<html>

<META http-equiv="Content-Type" content="text/html; charset=UTF-8">

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


3

Configuring Hosted Checkout

Pages

This chapter describes the following:



“Configuring Hosted Checkout Pages” on page 31







“Configuring Hosted Pages Using PayPal Manager” on page 31

“Using a Secure Token and Dynamically Passing Form Post Variables” on page 36

“Silent Posts” on page 38

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

Gateway hosted checkout pages to make the payment and complete the transaction. Since the pages are hosted on PayPal, you do not have to capture or store credit card information on your website, thereby helping towards achieving PCI compliance.

NOTE

:



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 the secure token and passing configuration parameters in a form post

Configuring Hosted Pages Using PayPal Manager

You can specify the content of your hosted checkout pages and configure their appearance to reflect the look and feel of your website. To do so, log into PayPal Manager and click on the

Settings tab. In the Hosted Checkout Pages section, you have the following options:





Setup

Customize

Setup

The Setup page on PayPal Manager enables you to select the information you want to collect and display on your hosted checkout pages and where you want to display the payment confirmation.


3

Configuring Hosted Checkout Pages

Configuring Hosted Pages Using PayPal Manager




3

You can perform tasks such as:





Configure your PayPal Express Checkout display and specify email addresses for live and test transactions.

Determine the URL and text of the link the buyer clicks on to cancel the payment on your website.









Select the billing and shipping information fields the buyer will be required to complete during checkout.

Choose to display your payment confirmation on either the hosted confirmation page or on your website. You can also specify the receipt header and footer text, the URL and text for the return link, and whether to use silent post.

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

Configure security features such as Accepted URLs to stop fraudsters from changing the monetary value of amounts being passed to and from the PayPal servers, Address

Verification System (AVS), and Card Security Code (CSC).

For complete details on these settings, click the Help button on the Setup page.


3



Customize




3

The Customize page allows you to customize your hosted checkout page. You can customize the header, background, title, button, and the order summary column of your payment page.

PayPal offers three design layouts for you to choose. Layout A is the default layout but you can choose from any of the three layouts offered.

Preview the design of your hosted checkout page. You can either change the design of your layout, or select and customize a different layout on this page. To make changes, double-click on the section you are trying to modify or the corresponding Click to Edit button for that section. On the pop-up that appears, click the color selector to change the color, or enter the appropriate URL, as needed.

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



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



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

Your buyers will see the updated payment page.





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

Undo Changes - Discard all changes you have made since the last time you saved the layout. Your buyers will see the last saved layout.

NOTE

: You must make all modifications (including changing layouts) within the same session, otherwise all changes will be lost and you will have to redo your changes. If the session times out, the design of the layout will remain at the version that was last published.

Customizing Your Layout



Header - You can change the following:

– Header height (Applicable to Layout A and B)

– Header color (Applicable to Layout B only)

– Header font type, size (Applicable to Layout A and B)

– Header font color (Applicable to Layout B only)

– Swap between displaying the business name or the business logo image

– Edit Header business name

– Position of the business name or the logo

– Upload a background image - .jpg, .jpeg, .gif, or .png. The maximum image size is

100kb.



Background (applicable to Layout B) - You can change the following:

– Background color

– Footer text color

– Upload image

– Repeat image option



Title and Button (applicable to Layout B) - You can change the following:

– Header color


36

3


Using a Secure Token and Dynamically Passing Form Post Variables



– Title bar color and title text color

– Button color and button text color

Order Summary Column (applicable to Layout B) - You can change the following:

– Column Color

– Upload image

– Repeat image option

Using a Secure Token and Dynamically Passing Form Post

Variables

You need to create a secure token and obtain the secure token ID prior to sending the form post with configuration parameters for the hosted pages. For details, see the

Secure Token

chapter.

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

Setup Params

Variable

CANCELURL

CSCREQUIRED

CSCEDIT

DISABLERECEIPT

EMAILCUSTOMER

ERRORURL

RETURNURL

SILENTPOSTURL

Description

The URL that customers would go to if pressing a

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

Maximum length: 512 characters.

Determines if the card security code is required. Values:

TRUE

or FALSE

Determines if the card security code is editable. Values:

TRUE

or FALSE

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

Send the buyer an email confirmation or not. Default value is FALSE.

The URL that customers are directed to if an error occurs. Maximum length: 512 characters.

The URL that customers are directed to after a transaction completes successfully. Maximum length:

512 characters.

The URL to which the Gateway will send Silent Post.

Maximum length: 512 characters.


Variable

SILENTPOSTFAILEDURL

TEMPLATE

URLMETHOD

Customize Params

Variable

PAGECOLLAPSEBGCOLOR

PAGECOLLAPSETEXTCOLOR

PAGEBUTTONBGCOLOR

PAGEBUTTONTEXTCOLOR

LABELTEXTCOLOR

Other HTML Post Params

Variable

MODE

PARMLIST

SECURETOKEN/SECURETOKENID


Using a Secure Token and Dynamically Passing Form Post Variables

3

Description

The return URL when Silent Post fails. Maximum length: 255 characters.

Determines whether to use one of the two redirect templates (Layout A or B) or the embedded template C.

Values are: TEMPLATEA or TEMPLATEB or MINLAYOUT

(for template C)

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

Description

Sets the color of the border around the embedded template C. Example:

PAGECOLLAPSEBGCOLOR=993300

Sets the color of the words “Pay with PayPal” and “Pay with credit or debit card”. Example:

PAGECOLLAPSETEXTCOLOR=990000

Sets the color of the Pay Now / Submit button.

Example: PAGEBUTTONBGCOLOR=AA66FF

Sets the color of the text on the Pay Now / Submit button. Example: PAGEBUTTONTEXTCOLOR=33FFFF

Sets the color of the text for “card number”, “expiration date”, ..etc. Example: LABELTEXTCOLOR=330000

Description

(Optional) Used in conjunction with secure token. It lets

Payflow know that the secure token passed in is a live or test token.Values: LIVE/TEST. Default is LIVE.

Used with a secure token. Passing in a string such as

PARMLIST=COMMENT1=Test&COMMENT2=Test2&US

ER1=123456

will make it so that Payflow will parse out the name-value pairs and use those to run thetransaction as well. This is for merchants that alreadyhave an existing PARMLIST they would be using withthe Payflow SDK and want an easy integration.

Used with the secure token.


38

3


Silent Posts

Variable

SHOWAMOUNT

SUBTOTAL

VERBOSITY

VERIFY

Description

If you pass in $0 amount and trans type = A, then if

SHOWAMOUNT=FALSE

, Payflow will not display the amount in the order summary table.Values:

TRUE/FALSE

Amount you pass to Payflow. It is displayed in the order summary section. This amount is only for display purposes and is not passed to the transaction servers.

Additional values that is returned from the transaction response to the merchant in the Silent Post. By default, there is no verbosity set which means the standard set of values that Silent Post currently uses is returned.

Passing in a verbosity will return the extra values that we get back in the transaction response.Value: HIGH

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

Silent Posts

The Silent Post feature returns data to your server using the HTML Post method whenever a transaction succeeds. The data is sent at the same time as when the Receipt page is displayed.

This feature is configured through https://manager.paypal.com

:





Go to Service Settings, then Setup

In the Hosted Checkout Pages tab, set Use Silent Post to Yes

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



Silent Posts

3

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


3


Silent Posts


4

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

“Activating Your Payflow Gateway Account” on page 42 .

“Host URL Addresses” on page 42

NOTE

: Each SDK includes full API documentation.

The Payflow SDK is available as a .NET or Java library.

NOTE

: Alternately you can build your own API by posting directly to the Gateway servers by

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

Preparing the Payflow Gateway Client Application

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

1. Download the Payflow SDK.

From the SDKs and Downloads page on x.com

, download the Payflow SDK appropriate for your platform.

2. Extract the files to a local directory.

3. Configure your firewall.

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

PayPal.

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

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

4. Read the Readme.txt file.

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


4

Payflow SDK

Activating Your Payflow Gateway Account

Activating Your Payflow Gateway Account

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

1. Log in to PayPal Manager at https://manager.paypal.com

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

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

Host URL Addresses

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



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



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


5

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 43

“Payflow Connection Parameters” on page 44







“User Parameter Data” on page 45

“Sale Transaction Example” on page 46

“Formatting Payflow Gateway Transactions” on page 46

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.


5

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.

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

44

Payflow Connection Parameters

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

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.



User Parameter Data

5

Parameter

HOSTADDRESS

HOSTPORT

TIMEOUT

PROXYADDRESS

PROXYPORT

PROXYLOGON

PROXYPASSWORD

Description

(Required) Gateway server name.

(Required) Use port 443.

(Required) Time-out period for the transaction. PayPal recommends a minimum time-out value of 30 seconds. The client begins tracking from the time that it sends the transaction request to the server.

(Optional) Proxy server address. Use the PROXY parameters for servers behind a firewall. Your network administrator can provide the values.

(Optional) Proxy server port.

(Optional) Proxy server logon ID.

(Optional) Proxy server logon password.

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

PARTNER

PWD

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


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


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

Limitations: 6 to 32 alphanumeric, case-sensitive characters


46

5


Sale Transaction Example

Sale Transaction Example

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

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











TRXTYPE

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

TENDER

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

ACCT

- The buyer’s credit card number

AMT

- The amount of the sale with two decimal places

EXPDATE

- The expiration date of the credit card

Typical Sale Transaction

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

TRXTYPE=S&TENDER=C&USER=MerchantUserID&PWD=Pwd4Gateway&PARTNER=PayPal&ACCT=

5105105105105100&EXPDATE=1215&AMT=23.45&COMMENT1=Airport Shuttle&BILLTOFIRS

TNAME=Jamie&BILLTOLASTNAME=Miller&BILLTOSTREET=123 Main St.&BILLTOCITY=San

Jose&BILLTOSTATE=CA&BILLTOZIP=951311234&BILLTOCOUNTRY=US&CVV2=123&CUSTIP=0.

0.0.0&VERBOSITY=HIGH

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

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

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

The following is an example response:

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

MATCH=Y

Formatting Payflow Gateway Transactions

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


6

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.





“Obtaining an Internet Merchant Account” on page 47

“About Credit Card Processing” on page 48









“Credit Card Features” on page 48

“Planning Your Gateway Integration” on page 49

“Core Credit Card Parameters” on page 51

“Submitting Account Verifications” on page 54

















“Submitting Authorization/Delayed Capture Transactions” on page 55

“Submitting Balance Inquiry Transactions” on page 56

“Submitting Card Present (SWIPE) Transactions” on page 57

“Submitting Credit Transactions” on page 59

“Submitting Inquiry Transactions” on page 61

“Submitting Partial Authorizations” on page 64

“Submitting Purchasing Card Transactions” on page 65

“Submitting Reference Transactions (Tokenization)” on page 66













“Submitting Sale Transactions” on page 69

“Submitting Soft Merchant Information” on page 70

“Submitting Voice Authorization Transactions” on page 71

“Submitting Void Transactions” on page 72

“Using Address Verification Service” on page 74

“Using Card Security Code” on page 75

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


6

Submitting Credit Card Transactions

About Credit Card Processing

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.

48

Credit Card Features

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

Transaction Type

Authorization

Account Verification

Billable

Yes

No



Planning Your Gateway Integration

6

Transaction Type

Balance Inquiry

Credit

Delayed Capture

Inquiry

Sale

Voice Authorization

Void

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

No

No

Yes

Yes

Yes

Billable

No

Yes

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


50

6


Planning Your Gateway Integration

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

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.



Core Credit Card Parameters

6

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

TENDER

TRXTYPE

ACCT

EXPDATE

Description

(Required) The method of payment. Values are:

 A

= Automated clearinghouse (ACH)





C

= Credit card

D

= Pinless debit





K

= Telecheck

P

= PayPal

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

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

 A

= Authorization





B

= Balance Inquiry

C

= Credit











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

(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

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

December 2015

.

Limitations: mmyy format


52

6



Parameter

AMT

COMMENT1

COMMENT2

CVV2

RECURRING

SWIPE

Description

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

Limitations: Specify the exact amount to the cent using a decimal point. For example, use 34.00 not 34. Do not include comma separators. For example, use 1199.95 not

1,199.95. Your processor or Internet Merchant Account provider may stipulate a maximum amount.

10 numeric characters plus decimal

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

Limitations: 128 alphanumeric characters

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


(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

(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

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

.

NOTE

:

SWIPE

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

Limitations: Alphanumeric and special characters


Parameter

ORDERID

BILLTOFIRSTNAME

BILLTOLASTNAME

BILLTOSTREET

BILLTOCITY

BILLTOSTATE

BILLTOZIP

BILLTOCOUNTRY

SHIPTOFIRSTNAME

SHIPTOLASTNAME

SHIPTOSTREET

SHIPTOCITY

SHIPTOSTATE

SHIPTOZIP



6

Description

(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

(Optional) Account holder's first name.


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


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

The address verification service verifies the STREET address.


(Optional) Bill-to city.

Limitations: 45-character string.

(Optional) Bill-to state.



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

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

(Optional) Bill-to country.

Limitations: 3-character country code.

(Optional) Ship-to first name.


(Optional) Ship-to last name.


(Optional) Ship-to street address.


(Optional) Ship-to city.


(Optional) Ship-to state.



(Optional) Ship-to postal code.



54

6


Submitting Account Verifications

Parameter

SHIPTOCOUNTRY

Description

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

.

Required Account Verification Parameters

To perform account verification, pass the following parameters:

Parameter

TRXTYPE

AMT

VERBOSITY

Description

(Required) Set to A.

Limitations: 1 alphanumeric character.

(Required) Set to 0.

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

Example Account Verification String

The following is an example of account verification:



Submitting Authorization/Delayed Capture Transactions

6

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

Y=HIGH &BILLTOZIP=95031

This is the response:

RESULT=0&PNREF=VFHA0FF8F27D&RESPMSG=Verified&AUTHCODE=667PNI&AVSADDR

=X&AVSZIP=X&HOSTCODE=A&PROCAVS=U&AMEXID=123456789012345&AMEXPOSDATA=

123456789012&TRANSTIME=2011-01-

11 18:42:01&AMT=0.00&ACCT=0005&EXPDATE=1215&CARDTYPE=3&IAVS=X

Submitting Authorization/Delayed Capture Transactions

An authorization (TRXTYPE=A) transaction places a hold on the 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.

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 69

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

NOTE

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


6


Submitting Balance Inquiry Transactions

Required Authorization Transaction Parameters

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

Parameter

ORIGID

Description

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

The PNREF parameter returns this ID, and it appears as the Transaction ID in

PayPal Manager reports.

Limitations: 12 case-sensitive alphanumeric characters.

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

56

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.

Processing Platforms Supporting Balance Inquiry Transactions

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

WorldPay

Required Balance Inquiry Parameters

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



Submitting Card Present (SWIPE) Transactions

6

Parameter

TRXTYPE

EXPDATE

VERBOSITY

Description

(Required) Set to B.


(Required) Expiration date of the pre-paid card in the format MMYY. For example, 1215 represents December 2015.

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

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


RESULT=0&PNREF=ERRV0A005933&RESPMSG=Approved&AUTHCODE=467PNI&HOSTCODE=000&T

RANSTIME=2012-02-

16 18:41:25&AMT=0.00&BALAMT=10.00&ACCT=4444&EXPDATE=1215&CARDTYPE=0

Submitting Card Present (SWIPE) Transactions

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

NOTE

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

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





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

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.


58

6


Submitting Card Present (SWIPE) Transactions

Processing Platforms Supporting Card-Present Transactions

The following processing platforms support card-present transactions.

American Express

American Express APAC

Elavon

Fifth Third Processing Solutions

First Data Merchant Services (FDMS) Nashville

First Data Merchant Services (FDMS) North

First Data Merchant Services (FDMS) South




Litle

Merchant e-Solutions

Moneris Solutions

Paymentech Salem

Paymentech Tampa

PayPal

SecureNet

TeleCheck


WorldPay

Card Present Transaction Syntax

Use the SWIPE parameter to pass the Track 1 or Track 2 data (the card’s magnetic stripe information). Include either Track 1 or Track 2 data (up to 80 alphanumeric characters). If

Track 1 is physically damaged, the POS application can send Track 2 data instead.

The track data includes the disallowed = (equal sign) character. To enable you to use the data, the SWIPE parameter must include a length tag specifying the number of characters in the track data. For this reason, in addition to passing the track data, the POS application counts the characters in the track data and passes that number as the length tag. For details on length tags,

see “Using Special Characters In Values” on page 43

. The length tag in the following example is [40].



Submitting Credit Transactions

6

NOTE

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

SWIPE

value includes this data.

TRXTYPE=S&TENDER=C&PARTNER=PayPal&USER=SuperMerchant&PWD=SuperMerchant&SWIP

E[40]=;4912000033330026=15121011000012345678?&AMT=21.00

Submitting Credit Transactions

The credit transaction (TRXTYPE=C) refunds the specified amount back to the cardholder. A credit transaction can contain a reference to the original transaction (referenced) or not (nonreferenced) depending on how your account is setup. To issue a credit, the original transaction can only be one of the following: a Sale (TRXTYPE=S), Delayed Capture (TRXTYPE=D) or

Voice Authorization (TRXTYPE=F). It is recommended that the merchant issue a credit only if the original transaction has already settled. Even though it is possible to issue a credit to a transaction that has not settled, it is recommended that you void such transactions.

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

Required Credit Transaction Parameters

The required parameter data for a credit transaction depends on the Allow non-referenced

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

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

Non-Referenced Credits Not Allowed

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

Parameter

ORIGID

Description






60

6


Submitting Credit Transactions

Set the value of ORIGID to the PNREF value returned for the original transaction. (PayPal

Manager reports display the PNREF as the Transaction ID.) If you do not specify an amount, the amount of the original transaction is credited to the cardholder.

Non-Referenced Credits Allowed

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

 ACCT

 EXPDATE

 AMT

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

ORIGID

Description

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

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.



Submitting Inquiry Transactions

6

ACCT

BILLTOEMAIL

BILLTOSTATE

COMMENT2

EXPDATE

SHIPTOCOUNTRY

SHIPTOSTATE

AMT BILLTOCITY

BILLTOMIDDLENAME BILLTOLASTNAME

BILLTOSTREET BILLTOZIP

COMPANYNAME

INVNUM

SHIPTOFIRSTNAME

SHIPTOSTREET

CUSTCODE

PONUM

BILLTOCOUNTRY

BILLTOPHONENUM

COMMENT1

CUSTIP

SHIPTOCITY

SHIPTOMIDDLENAME SHIPTOLASTNAME

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.

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:


62

6



Parameter

ORIGID

Description





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

CUSTREF

STARTTIME

Description

(Required) Merchant-defined identifier for reporting and auditing purposes. For example, you can set CUSTREF to the invoice number.

You can use CUSTREF when performing inquiry transactions. To make sure that you can always access the correct transaction when performing an inquiry, provide a unique CUSTREF when submitting any transaction, including retries.


(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




6

Parameter

ENDTIME

Description

(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

SECURETOKEN

Description

(Required) A value the Payflow server created upon your request for storing transaction data.


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

Inquiry Parameter String Using the Secure Token

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

TRXTYPE=I&TENDER=C&PARTNER=PayPal&PWD=SuperUserPassword&USER=SuperMerchant&

VERBOSITY=HIGH&VENDOR=SuperMerchant&SECURETOKEN=FmyM1y7wy8kiS6aumnMPhTQN&VE

RBOSITY=HIGH

The following is the response string.


64

6


Submitting Partial Authorizations

RESULT=0&PNREF=VFHE1A0CB0A9&TRANSSTATE=6&ORIGRESULT=0&ORIGPNREF=VFHE1A0CB0A

8&RESPMSG=Approved&AUTHCODE=010101&AVSADDR=Y&AVSZIP=Y&HOSTCODE=00&PROCAVS=Y

&DATE_TO_SETTLE=2011-02-04 16:16:50&TRANSTIME=2011-02-

04 16:16:50&BILLTOFIRSTNAME=James&BILLTOLASTNAME=Smith&AMT=555.00&ACCT=0002

&EXPDATE=0120&CARDTYPE=0&IAVS=N

Submitting Partial Authorizations

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

When To Use Partial Authorizations

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

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

You can take either of the following actions:





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

$20.00.

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

(Void) for $80.00.

Required Partial Authorization Parameters

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

Parameter

PARTIALAUTH

VERBOSITY

Description

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


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



Submitting Purchasing Card Transactions

6

Example Partial Authorization

The following is an example partial authorization.

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

TRXTYPE=A&TENDER=C&AMT=100.00&ACCT=4111111111111111&EXPDATE=0119

&PARTIALAUTH=Y&VERBOSITY=HIGH

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

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

RESULT=0&PNREF=VRNS1A3B33C9&RESPMSG=Partial

Approval &AUTHCODE=11111&HOSTCODE=E&PROCAVS=U&TRANSTIME=2010-04-21

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

RESPMSG

is Partial Approval, AMT is now the actual amount approved, ORIGAMT is the original requested amount, and BALAMT is the balance on the card.

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

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

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

$20.00.

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

(void) for $80.

Submitting Purchasing Card Transactions

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

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 Level 3 Transactions” on page 143 .

NOTE

: The PayPal processor does not support purchasing card transactions.


66

6


Submitting Reference Transactions (Tokenization)

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. Except for dollar amount data, which triggers a filter if out of range,

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.

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




6









Delayed capture

Sale

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

Void

Fields Copied From Reference Transactions

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

ACCTTYPE

ACCT

EXPDATE

BILLTOFIRSTNAME

BILLTOMIDDLENAME

BILLTOLASTNAME

BILLTOSTREET

BILLTOCITY

BILLTOSTATE

BILLTOZIP

BILLTOCOUNTRY

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:

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.


68

6



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

 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


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



Submitting Sale Transactions

6

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

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

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.


70

6


Submitting Soft Merchant Information

TRXTYPE=S&TENDER=C&USER=SuperUser&PWD=SuperUserPassword&VENDOR=SuperUser&PA

RTNER=PayPal&ACCT=5105105105105100&EXPDATE=1215&CVV2=123&AMT=99.00&BILLTOFI


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 57

“Using Card Security Code” on page 75

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.

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.



Submitting Voice Authorization Transactions

6

Soft Merchant Information (SM Record)

Soft merchant information is for American Express credit cards only. Typically aggregators

(and petroleum merchants) pass soft merchant information to the processor in Gateway parameter fields such as the following:

 MERCHANTNAME

 MERCHANTSTREET

 MERCHANTCITY

 MERCHANTSTATE

 MERCHANTNAME

 MERCHANTZIP

 MERCHANTCOUNTRYCODE

 MERCHANTLOCATIONID

 MERCHANTID

 MERCHANTCONTACTINFO

NOTE

: Paymentech Salem processor only: To take advantage of this level of soft descriptor, you must be approved by the Paymentech Risk/Credit department. Upon approval,

Paymentech sets a flag at the transaction division to enable you to send the preceding parameters. If the flag is not set and you send the parameters, your transaction is rejected with Error 258.

Merchant Descriptor (M Record)

A merchant descriptor defines the merchant name and product that appears on the account 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.

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.


72

6


Submitting Void 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

AUTHCODE

Description

(Required for voice authorizations) Returned only for approved voice authorization transactions. AUTHCODE is the approval code received over the phone from the processing network.


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

TRXTYPE=F&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant&P

WD=x1y2z3&AUTHCODE=AB3456&ACCT=5555555555554444&EXPDATE=1215&AMT=123.00&VER

BOSITY=HIGH

Submitting Void Transactions

The void transaction (TRXTYPE=V) prevents authorizations from being captured, and delayed captures, sales and voice authorizations from being settled.

You cannot void another void transaction or any inquiry type transactions. The void transaction and the original transaction will not appear on the customer’s statement.

PayPal will issue an authorization reversal as part of the void transaction for debit and credit cards if the processor supports it. Because the bank or issuer ultimately decides whether to honor authorization reversals, there is no accurate way to determine if an authorization reversal was completed and the hold on funds has been removed.



Submitting Void Transactions

6

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:

Parameter

ORIGID

Description

(Required by some transaction types) ID of the original transaction that is being referenced. The PNREF parameter returns the ID, and it appears as the

Transaction ID in PayPal Manager reports.

Limitations: 12 case-sensitive alphanumeric characters

Fields Copied From the Original Transaction Into the Void Transaction

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

SWIPE

. These parameters retain their original values.)

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

COMMENT2

CUSTIP

BILLTOFIRSTNAME

INVNUM

SHIPTOFIRSTNAME

SHIPTOSTREET

SWIPE

BILLTOZIP

AMT

COMPANYNAME

DUTYAMT

BILLTOMIDDLENAME

PONUM

SHIPTOMIDDLENAME

SHIPTOZIP

TAXAMT

BILLTOCITY

BILLTOCOUNTRY

BILLTOEMAIL

BILLTOLASTNAME

SHIPTOCITY

SHIPTOLASTNAME

BILLTOSTATE

BILLTOPHONENUM

COMMENT1

CUSTCODE

EXPDATE

FREIGHTAMT

SHIPTOCOUNTRY

SHIPTOSTATE

BILLTOSTREET

TAXEXEMPT


74

6


Using Address Verification Service

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 = no match, 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

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

6

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.

On most cards (Diners Club, Discover, Mastercard and Visa) the card security code is a 3-digit number printed on the back of the card (usually in the signature field). All or part of the card number appears before the card security code (567 in the example). American Express prints a

4-digit number (1122 in the example) on the front of the card, above and to the right of the embossed account number. Make sure that you explain this to your customers.

To validate the card security code in a transaction, pass the card security code value in the

CVV2

parameter in your request. The response parameter CVV2MATCH returns the result of the card security code check.

NOTE

: To comply with credit card association regulations, do not store the card security code value that you pass in the CVV2 parameter.

Card security code

The following is an example request parameter string.

TRXTYPE=S&TENDER=C&USER=SuperUser&PWD=SuperUserPassword&VENDOR=SuperUser&PA

RTNER=PayPal&ACCT=5105105105105100&EXPDATE=1215&CVV2=123&AMT=99.00&BILLTOFI


Jose&BILLTOSTATE=CA&BILLTOZIP=12345

NOTE

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


6


Using Card Security Code


7

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

PayPal’s simulated network processes transactions directed to the URL.

Testing Guidelines

Follow these guidelines for testing.



While testing, use only the credit card numbers for testing. Other numbers produce an error.





Expiration date must be a valid date in the future. Use the format mmyy.

To view the credit card processor that you have selected for testing, see PayPal Manager.

Processors Other Than PayPal

For processors other than the PayPal processor, use the guidelines below.

Credit Card Numbers for Testing

For processors other than PayPal, use the following credit card numbers for testing. Any other card number produces a general failure.

American Express

American Express

American Express Corporate


378282246310005

371449635398431

378734493671000

31 July 2012 77

78

7

Testing Transactions

Processors Other Than PayPal

Diners Club

Discover

Discover

JCB

JCB

MasterCard

MasterCard

Visa

Visa

Visa

38520000023237

6011111111111117

6011000990139424

3530111333300000

3566002020360505

5555555555554444

5105105105105100

4111111111111111

4012888888881881

4222222222222

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

$0 – $1000

$1001 – $2000

$2001+

Result

RESULT

value 0 (Approved)

Certain amounts in this range return specific PayPal results. You can generate the results by adding $1000 to that RESULT value. For example, for RESULT value 13 (Referral), submit the amount 1013.

If the amount is in this range but does not correspond to a result supported by this testing mechanism, Payflow returns RESULT value 12 (Declined).

RESULT

value 12 (Declined)

Result Values Based On Amount Submitted and Processor

This table lists the RESULT values that you can generate using the amount of the transaction.

To generate a specific value, submit an amount of 1000 plus the RESULT value number (for example, submit an amount of 1013 for a RESULT value of 13).

Processing Platform

American Express Brighton

Elavon

RESULT Values Available for Testing

0, 12, 13, 104, 1000

0, 12, 13, 104


1

2

3

4

5

7

12

13



7

Processing Platform

First Data Merchant Services North

First Data Merchant Services Nashville

First Data Merchant Services South



Paymentech Salem (New Hampshire)

Paymentech Tampa


Vantiv (formerly Fifth Third Processing Solutions)

RESULT Values Available for Testing

0, 4, 5, 12, 13, 23, 24,114, 1000

0, 12, 13, 104

0, 12, 13, 104

0, 4, 5, 8, 12, 13, 23, 24, 104, 111, 114, 1000

0, 4, 5, 12, 13, 23, 24, 30, 100, 104, 114, 1000

0, 12, 13, 104

0, 3, 4, 5, 12, 13, 23, 24, 1000

0, 4, 12, 13, 23, 104, 114, 1000

0, 4, 5, 12, 13, 23, 24,114, 1000

Result Values Based On Alternate Generation Methods

The following table shows another method for obtaining RESULT values. Servers do not return non-zero RESULT values from processors. Therefore, you cannot simulate non-zero RESULT values using the amount. In some cases, you may obtain certain results using the RESULT value plus 1000 even though this table suggests an alternate means of obtaining the RESULT value.

RESULT value

0

Definition

Approved

User authentication failed

Invalid tender

Invalid transaction type

Invalid amount

Invalid merchant information

Field format error

Declined

Referral

How to test using Payflow Gateway

Use an AMOUNT of $1000 or less

For all processors except Global Payments Central

(MAPP) and FDI

Credit (C) and force (F) transactions will always be approved regardless of dollar amount or card number

Use an invalid PWD

Use an invalid TENDER, such as G

Use an invalid TRXTYPE, such as G

Use an invalid AMOUNT, such as –1

Use the AMOUNT 1005 - Applies only to the following processors: Global Payments East and Central, and

American Express

Submit a delayed capture transaction with no ORIGID

Use the AMOUNT 1012 or an AMOUNT of 2001 or more

Use the AMOUNT 1013


80

50

99

100

101

103

104

105

108

111

7



23

24

25

RESULT value

19

22

29

30

112

113

Definition

Original transaction ID not found

Invalid ABA number

Invalid account number

Invalid expiration date

Transaction type not mapped to this host (Processor)

Invalid XML document

Duplicate Transaction

Insufficient funds available

General error

Invalid transaction returned from host (Processor)

Time-out value too small

Error reading response from host (Processor)

Timeout waiting for processor response

Credit error

Void error

Capture error

How to test using Payflow Gateway

Submit a delayed capture transaction with an invalid

ORIGID

Applies only to ACH transactions – submit an invalid

ABA number (8 digits)

Submit an invalid account number, for example,

000000000000000

Submit an invalid expiration date, for example, 0298

Submit a transaction for a card or tender you are not currently set up to accept, for example, a Diners card if you aren’t set up to accept Diners

Pass a bad XML document (XMLPay users only)

Use the AMOUNT 1030 - Only applies to Global

Payments East and Global Payments Central processors

Use the AMOUNT 1050 - Only applies to Paymentech


Payments East


Payments East and Central

Set timeout value to 1

Use the AMOUNT 1103

Use the AMOUNT 1104

Failed AVS check

Cannot exceed sales cap

Attempt to credit an authorization

Attempt to void a captured authorization

Capture an authorization transaction twice or attempt to capture a transaction that is not an authorization transaction

You cannot generate this RESULT value by submitting an amount of 1112, but must submit a value for Address Verification Service that will fail; in production, this error occurs only if your account is configured by PayPal customer service to use the

“AVS Deny” feature

Applies to ACH transactions only




7

RESULT value

114

1000

Definition How to test using Payflow Gateway

CVV2 Mismatch Use the AMOUNT 1114. Only applies to TSYS

Acquiring Solutions, Merchant e-Solutions, and

Global Payments East and Global Payments Central processors

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

334-666

667

or higher or begins with a nonnumeric character

Example BILLTOSTREET

Value

24285 Elm

49354 Main

79232 Maple

The following table tests AVSZIP.

AVSADDR Result

Y

N

X

Submitted Value for BILLTOZIP Example BILLTOZIP Value

00000-50000

00382

50001-99999

Any value (if street address is 667 or higher or begins with a non-numeric character)

94303

BILLTOSTREET=79232 Maple,

BILLTOZIP=20304

N

X

AVSZIP Result

Y


7


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

001-300

Y

Y

301-600

601

or higher

N

X

82

PayPal Processor

For the PayPal processor, use the following guidelines.

Credit Card Numbers for Testing

For the PayPal processor, use the following credit card numbers for testing. Any other card number produces a general failure.

American Express

American Express

Amex Corporate

Australian BankCard

Diners Club

Diners Club

Discover

Discover

378282246310005

371449635398431

378734493671000

5610591081018250

30569309025904

38520000023237

6011111111111117

6011000990139424



PayPal Processor

7

JCB

JCB

MasterCard

MasterCard

Visa

Visa

Visa

3530111333300000

3566002020360505

5555555555554444

5105105105105100

4111111111111111

4012888888881881

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.

Result

0

3

4

5

Definition

Approved


Invalid amount

Invalid merchant information

How to test

Use an AMOUNT of 10000 or less

Use the AMOUNT 10402

Use any of these as AMOUNT:



10400







10401

10403

10404






10548

10549


84

7


PayPal Processor

Result

7

12

13

23

Definition

Field format error

Declined

Referral

Invalid account number

How to test




10405





10406

10407









10408

10409

10410

10412

















10413

10416

10419

10420

10421

10509

10512

10513















10514

10515

10516

10517

10518

10540

10542






10417

15002









15005

15006

15028

15039







10544

10545

10546





10519





10521

10522









10527

10535

10541

10543


Result

24

30

105

112

114

1000


PayPal Processor

7

Definition

Invalid expiration date

How to test




10502



10508

Use the AMOUNT 10536 Duplicate Transaction

Credit error

Failed AVS check

Attempt to credit an authorization


CVV2 Mismatch Use the AMOUNT 10504

Generic Host (Processor) Error Use an AMOUNT other than those listed in this column


7


PayPal Processor


8

Transaction Responses

When a transaction finishes, the Payflow server returns a response string made up of namevalue pairs. The following is an example response string:

RESULT=0&PNREF=EFHP0D426A53&RESPMSG=APPROVED&AUTHCODE=25TEST&AVSADDR=Y&AVSZ

IP=N&CVV2MATCH=Y

Credit Card Transaction Responses

The table below describes values that can be returned in response strings.

Field

PNREF

PPREF

RESULT

CVV2MATCH

Description

Gateway transaction ID, a unique number that identifies the transaction.

Character length and limitations: 12 alphanumeric characters

Unique transaction ID of the payment.

Character length and limitations: 17-character string

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

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)


88

8


Credit Card Transaction Responses

Field

RESPMSG

AUTHCODE

AVSADDR

AVSZIP

IAVS

PROCAVS

PROCCVV2

Description

The response message returned with the transaction result. Exact wording varies.

Sometimes a colon appears after the initial RESPMSG followed by more detailed information.

NOTE

: For account verification transactions, RESULT=0 with RESPMSG=Verified means a zero dollar authorization has been successfully performed.

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

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.


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.


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.


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.


The raw address verification service response returned by the processor. This field is not normalized and is returned when VERBOSITY is set to HIGH.

Character length and limitations: 1 character

The raw CVV2 response returned by the processor. This field is not normalized and is returned when VERBOSITY is set to HIGH.




Credit Card Transaction Responses

8

Field

HOSTCODE

RESPTEXT

PROCCARDSECURE

ADDLMSGS

PAYMENTTYPE

CORRELATIONID

Description

The raw response code returned by the processor. This field is not normalized and is returned when VERBOSITY is set to HIGH. Use RESPTEXT to obtain the response message from the processor. For additional PayPal processor response code information, refer to the PayPal API error codes . For all other processors, please contact your merchant bank or processor directly.

Character length and limitations: 6 characters

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.


The raw Buyer Authentication response returned by the processor. This field is not normalized and is returned when VERBOSITY is set to HIGH.


Additional error message that indicates the use of a features that has been disabled.

Character length and limitations: Up to 1048 characters. Typically 50 characters.

(PayPal only.) Returns instant if the payment is instant or echeck if the payment is delayed (DP) on the PayPal processor.

Character length and limitations: 7-character string

(PayPal only.) Value used for tracking this Direct Payment transaction.


AMEXID

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.


AMT

ORIGAMT

This field returns the transaction amount or if performing a partial authorization it will return the amount approved for the partial authorization.

Partial authorizations: Original amount submitted for authorization.


90

8


Address Verification Service Responses From PayPal

Field

CARDTYPE

EMAILMATCH

PHONEMATCH

EXTRSPMSG

TRANSTIME

DUPLICATE

DATE_TO_SETTLE

Description

The credit card type. Is returned in an inquiry response when you send a VERBOSITY request parameter value of HIGH.

Is one of the following values for currently used cards:

 0

= Visa





1

= MasterCard

2

= Discover







3

= American Express

4

= Diner’s Club

5

= JCB

Verifies whether the BILLTOEMAIL value sent is what is on file with the processor.

(American Express processor only)


Verifies whether the BILLTOPHONENUM value sent is what is on file with the processor. (American Express processor only)


Additional processor-related messages.

Time of the transaction. The following is an example response in the format returned:

TRANSTIME=2010-08-11 22:53:18

Character length and limitations: See example

Is returned with one of the following values:







DUPLICATE=2

— ORDERID has already been submitted in a previous request with the same ORDERID.

DUPLICATE=1

— The request ID has already been submitted for a previous request.

DUPLICATE=-1

— The Gateway database is not available. PayPal cannot determine whether this is a duplicate order or request.

The date a transaction will settle. This parameter is returned in the response for inquiry transactions only (TRXTYPE=I).

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.



Address Verification Service Responses From PayPal

8

R

S

N

P

F

I

G

X

Y

U

W

Z

All other

C

D

E

A

B

PayPal processor

Address

Verification

Service code Meaning

Address

International “A”

International “N”

International “X”

Not allowed for MOTO (Internet/Phone) transactions

UK-specific “X”

Global Unavailable

International Unavailable

No

Postal (International “Z”)

Retry

Service not Supported

Unavailable

Whole Zip

Exact Match

Yes

Zip

Y

Y

X

N

N

X

X

X

N

N

Y

X

X

N

Y

X

AVSADDR

Y

Y

The following is an example Authorization request string that sets VERBOSITY to HIGH.

Payflow returns the PROCAVS value in the response.

Y

Y

X

Y

Y

X

X

X

N

Y

Y

X

X

N

Y

X

AVSZIP

N

N

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


8


Card Security Code Results

Card Security Code Results

92

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.

S

U

N

P

PayPal Processor CVV2 Code

M

X

All other

PayPal Processor Code

Description

Match

No Match

Not Processed

Service Not Supported

Unavailable

No Response

X

X

N

X

X

X

PROCVV2MATCH

Y

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.

S

U

N

P


M


Description

Match

No Match

Not Processed

Service Not Supported

Unavailable

X

X

N

X

PROCVV2MATCH

Y



X

All other


Description

No Response


BALAMT Response and Stored Value Cards

8

PROCVV2MATCH

X

X

BALAMT Response and Stored Value Cards

Transactions meeting American Express reporting and statement requirements may return

BALAMT

when the transaction involves a stored value card. Stored value cards typically are offered as gift cards, allowing the customer to spend any amount up to the balance remaining on the card. A card must be active and not compromised for BALAMT to return the card balance. If the card is used to purchase merchandise exceeding the card balance, American

Express declines the transaction and returns the card balance in BALAMT.

NOTE

: Not all processors support BALAMT when a transaction involves a stored value card.

American Express Stored Value Card Example

The following authorization request is for a purchase of 123.00.

TRXTYPE=A&TENDER=C&PWD=x1y2z3&PARTNER=PayPal&VENDOR=SuperMerchant&USER=Supe rMerchant&ACCT=5555555555554444&EXPDATE=1215&AMT=123.00&BILLTOSTREET=5199 M

APLE&BILLTOZIP=94588

Because the response returns a BALAMT of 99.00, the authorization is declined.

RESULT=12&PNREF=VXYZ01234567&RESPMSG=DECLINED&BALANCE=99.00&AVSADDR=Y&AVSZI

P=N

PNREF

The PNREF is a unique transaction identification number issued by PayPal that identifies the transaction for billing, reporting, and transaction data purposes. The PNREF value appears in the Transaction ID column in PayPal Manager reports.





The PNREF value is used as the ORIGID value (original transaction ID) in delayed capture transactions (TRXTYPE=D), credits (TRXTYPE=C), inquiries (TRXTYPE=I), and voids

(TRXTYPE=V).

The PNREF value is used as the ORIGID value (original transaction ID) value in reference transactions for authorization (TRXTYPE=A) and sale (TRXTYPE=S).

The PNREF value is a 12-character string of printable characters, for example:


94

8


RESULT Values and RESPMSG Text

 VADE0B248932

 ACRAF23DB3C4

NOTE

: Printable characters also include symbols other than letters and numbers such as the question mark (?). A PNREF value typically contains letters and numbers only.

The PNREF in a transaction response tells you that your transaction is connecting to PayPal.

RESULT Values and RESPMSG Text

The RESULT parameter is the first response parameter returned in the response string. The value of RESULT indicates the overall status of the transaction attempt:



A value of 0 (zero) indicates that no errors occurred and the transaction was approved.





NOTE

: For account verification transactions, RESULT=0 with RESPMSG=Verified means that a zero dollar authorization is successful.

A value less than 0 indicates that a communication error occurred. In this case, no transaction is attempted.

A value greater than 0 indicates a decline or error (except in the case of RESULT 104. See the following table).

The response message (RESPMSG) provides a brief description for decline or error results.

To obtain the raw response code and message returned by the processor set VERBOSITY to

HIGH

in your request and capture the response values of the HOSTCODE and RESPTEXT parameters.

For PayPal Processor Only:

When interpreting RESULT values for the PayPal processor, note the following:





When RESULT=0, warning information may be returned that is useful to the request application. See the PayPal API documentation on x.com for detailed information on corrective actions.

When RESULT=104, log in to the PayPal website to determine whether the transaction actually went through. If the transaction does not appear in the History section, retry it.

RESULT

0

RESPMSG and Explanation

Approved

NOTE

: PayPal processor: Warning information may be returned that may be useful to the request applicaton. See the PayPal API documentation on x.com for information on corrective actions.


13

19

20

22

23

24

2

3

4

5

9

10

11

12

6

7

8

RESULT

1



8


User authentication failed. Error is caused by one or more of the following:



Login information is incorrect. Verify that USER, VENDOR, PARTNER, and

PASSWORD

have been entered correctly. VENDOR is your merchant ID and USER is the same as VENDOR unless you created a Payflow Pro user. All fields are case sensitive.







Invalid Processor information entered. Contact merchant bank to verify.

"Allowed IP Address" security feature implemented. The transaction is coming from an unknown IP address. See PayPal Manager online help for details on how to update the allowed IP addresses.

You are using a test (not active) account to submit a transaction to the live PayPal servers. Change the host address from the test server URL to the live server URL

Invalid tender type. Your merchant bank account does not support the following credit card type that was submitted.

Invalid transaction type. Transaction type is not appropriate for this transaction. For example, you cannot credit an authorization-only transaction

Invalid amount format. Use the format: “#####.##” Do not include currency symbols or commas.

Invalid merchant information. Processor does not recognize your merchant account information. Contact your bank account acquirer to resolve this problem.

Invalid or unsupported currency code

Field format error. Invalid information entered. See RESPMSG.

Not a transaction server

Too many parameters or invalid stream

Too many line items

Client time-out waiting for response

Declined. Check the credit card number, expiration date, and transaction information to make sure they were entered correctly. If this does not resolve the problem, have the customer call their card issuing bank to resolve.

Referral. Transaction cannot be approved electronically but can be approved with a verbal authorization. Contact your merchant bank to obtain an authorization and submit a manual Voice Authorization transaction.

Original transaction ID not found. The transaction ID you entered for this transaction is not valid. See RESPMSG.

Cannot find the customer reference number

Invalid ABA number

Invalid account number. Check credit card number and bank account number and resubmit.

Invalid expiration date. Check card expiration date and re-submit.


96

33

34

35

36

30

31

32

37

50

51

52

27

28

29

99

100

101

8



RESULT

25

26

102


Invalid Host Mapping. Error is caused by one or more of the following:



You are trying to process a tender type such as Discover Card, but you are not set up with your merchant bank to accept this card type.



You are trying to process an Express Checkout transaction when your account is not set up to do so. Contact your account holder to have Express Checkout added to your account.

Invalid vendor account. Login information is incorrect. Verify that USER, VENDOR,

PARTNER

, and PASSWORD have been entered correctly. VENDOR is your merchant ID and USER is the same as VENDOR unless you created a Payflow Pro user. All fields are case sensitive.

Insufficient partner permissions

Insufficient user permissions

Invalid XML document. This could be caused by an unrecognized XML tag or a bad

XML format that cannot be parsed by the system.

Duplicate transaction

Error in adding the recurring profile

Error in modifying the recurring profile

Error in canceling the recurring profile

Error in forcing the recurring profile

Error in reactivating the recurring profile

OLTP Transaction failed

Invalid recurring profile ID

Insufficient funds available in account

Exceeds per transaction limit

Permission issue. Attempting to perform a transaction type, such as Sale or

Authorization, that is not allowed for this account.

General error. See RESPMSG.

Transaction type not supported by host

Time-out value too small

PayPal Australia: Invalid transaction returned from host (can be treated as an invalid transaction or a decline)

Processor not available

The financial host was unable to communicate with the external processor. These transactions do not make it out of the Payflow network and will not settle or appear on processor reports.


RESULT

103

104

109

110

111

105

106

107

108



8


Error reading response from host

The financial host could not interpret the response from the processor. This error can result in an uncaptured authorization if the transaction is an authorization or a sale, except on the following processors:



PayPal Australia: Time-out reversal logic should reverse the transaction. According to PayPal Australia, this is a best effort and is not guaranteed.





Global Payments Central, Citi Bank Singapore: Time-out reversal logic should reverse the transaction.

PayPal: The transaction might settle. There is no time-out reversal process on

PayPal.

Timeout waiting for processor response.

Try your transaction again.

The Payflow gateway sent the transaction to the processor, but the processor did not respond in the allotted time. This error can result in an uncaptured authorization if the transaction is an authorization or a sale, except on the following processors:



PayPal Australia: Time-out reversal logic should reverse the transaction. According to PayPal Australia, this is a best effort and is not guaranteed.





Global Payments Central, Citi Bank Singapore: Time-out reversal logic should reverse the transaction.

PayPal: The transaction might settle. There is no time-out reversal process on

PayPal.

Credit error. Make sure you have not already credited this transaction, or that this transaction ID is for a creditable transaction. (For example, you cannot credit an authorization.)

Host not available

The Payflow transaction server was unable to communicate with the financial host.

This error is an internal failure, and the transaction will not make it to the processor.

Duplicate suppression time-out

Void error. RESPMSG. Make sure the transaction ID entered has not already been voided. If not, then look at the Transaction Detail screen for this transaction to see if it has settled. (The Batch field is set to a number greater than zero if the transaction has been settled). If the transaction has already settled, your only recourse is a reversal

(credit a payment or submit a payment for a credit)

Time-out waiting for host response

The Payflow transaction server times out waiting for a financial host to respond. This error can result in uncaptured authorizations on all platforms, or settled sales on PayPal

Australia, Global Payments Central, and PayPal.

Referenced auth (against order) Error

Capture error. Either an attempt to capture a transaction that is not an authorization transaction type, or an attempt to capture an authorization transaction that has already been captured.


98

8



118

120

121

122

125

126

127

128

132

133

114

115

116

117

RESULT

112

113


Failed AVS check. Address and zip code do not match. An authorization may still exist on the cardholder’s account.

Merchant sale total will exceed the sales cap with current transaction. ACH transactions only.

Card Security Code (CSC) Mismatch. An authorization may still exist on the cardholder’s account.

System busy, try again later

VPS Internal error. Failed to lock terminal number. For Moneris Solutions, another transaction or settlement is in process. Rerun the transaction later.

Failed merchant rule check. One or more of the following three failures occurred:An attempt was made to submit a transaction that failed to meet the security settings specified on the PayPal Manager Security Settings page. If the transaction exceeded the

Maximum Amount security setting, then no values are returned for AVS or CSC. AVS validation failed. The AVS return value should appear in the RESPMSG. CSC validation failed. The CSC return value should appear in the RESPMSG.

Invalid keywords found in string fields

Attempt to reference a failed transaction

Not enabled for feature

Merchant sale total will exceed the credit cap with current transaction. ACH transactions only.

Fraud Protection Services Filter — Declined by filters

Fraud Protection Services Filter — Flagged for review by filters

NOTE

:

RESULT

value 126 indicates that a transaction triggered a fraud filter. This is not an error, but a notice that the transaction is in a review status. The transaction has been authorized but requires you to review and to manually accept the transaction before it will be allowed to settle.

RESULT

value 126 is intended to give you an idea of the kind of transaction that is considered suspicious to enable you to evaluate whether you can benefit from using the

Fraud Protection Services.

To eliminate RESULT 126, turn the filters off.

For more information, see the fraud documentation for your payments solution.

Fraud Protection Services Filter — Not processed by filters

Fraud Protection Services Filter — Declined by merchant after being flagged for review by filters

Card has not been submitted for update

Data mismatch in HTTP retry request


1017

1021

1022

1023

1041

1042

1043

1001

1002

1003

1004

1011

1012

1013

1014

151

200

201

600

601

1000

1016

RESULT

150



8


Issuing bank timed out

FDRA reported a timeout between their system and the bank. This error will be reversed by time-out reversal. According to PayPal Australia, this is a best effort and is not guaranteed.

Issuing bank unavailable

Reauth error

Order error

Cybercash Batch Error

Cybercash Query Error

Generic host error. This is a generic message returned by your credit card processor.

The RESPMSG will contain more information describing the error.

Buyer Authentication Service unavailable

Buyer Authentication Service — Transaction timeout

Buyer Authentication Service — Invalid client version

Buyer Authentication Service — Invalid timeout value




Buyer Authentication Service — Merchant is not enrolled for Buyer

Authentication Service (3-D Secure)

Buyer Authentication Service — 3-D Secure error response received. Instead of receiving a PARes response to a Validate Authentication transaction, an error response was received.

Buyer Authentication Service — 3-D Secure error response is invalid. An error response is received and the response is not well formed for a Validate Authentication transaction.

Buyer Authentication Service — Invalid card type

Buyer Authentication Service — Invalid or missing currency code

Buyer Authentication Service — merchant status for 3D secure is invalid

Buyer Authentication Service — Validate Authentication failed: missing or invalid

PARES

Buyer Authentication Service — Validate Authentication failed: PARES format is invalid

Buyer Authentication Service — Validate Authentication failed: Cannot find successful Verify Enrollment


100

8



1050

1051

1052

RESULT

1044

1045

1046

1047

1048

1049


Buyer Authentication Service — Validate Authentication failed: Signature validation failed for PARES

Buyer Authentication Service — Validate Authentication failed: Mismatched or invalid amount in PARES

Buyer Authentication Service — Validate Authentication failed: Mismatched or invalid acquirer in PARES

Buyer Authentication Service — Validate Authentication failed: Mismatched or invalid Merchant ID in PARES

Buyer Authentication Service — Validate Authentication failed: Mismatched or invalid card number in PARES

Buyer Authentication Service — Validate Authentication failed: Mismatched or invalid currency code in PARES

Buyer Authentication Service — Validate Authentication failed: Mismatched or invalid XID in PARES

Buyer Authentication Service — Validate Authentication failed: Mismatched or invalid order date in PARES

Buyer Authentication Service — Validate Authentication failed: This PARES was already validated for a previous Validate Authentication transaction

RESULT Values For Communications Errors

A RESULT value less than zero indicates that a communication error occurred. In this case, no transaction is attempted.

A value of -1 or -2 usually indicates a configuration error caused by an incorrect URL or by configuration issues with your firewall. For information on firewall configuration, see

“Preparing the Payflow Gateway Client Application” on page 41

. A value of -1 or -2 can also be possible if the Gateway servers are unavailable, or you specified an incorrect server or socket pair. A value of -1 can also result when there are internet connectivity errors. Contact

Customer Service regarding any other errors.

Details of the response message may vary slightly from the message shown in the table, depending on your SDK integration.

RESULT

-1

-2

-5

Description

Failed to connect to host

Failed to resolve hostname

Failed to initialize SSL context




8

-100

-103

-104

-105

-106

-32

-40

-41

-99

-28

-29

-30

-31

-24

-25

-26

-27

-20

-21

-22

-23

-12

-13

-14

-15

-8

-9

-10

-11

RESULT

-6

-7

Description

Parameter list format error: & in name

Parameter list format error: invalid [ ] name length clause

SSL failed to connect to host

SSL read failed

SSL write failed

Proxy authorization failed

Timeout waiting for response

Select failure

Too many connections

Failed to set socket options

Proxy read failed

Proxy write failed

Failed to initialize SSL certificate

Host address not specified


Failed to create a socket

Failed to initialize socket layer

Parameter list format error: invalid [ ] name length clause

Parameter list format error: name

Failed to initialize SSL connection

Invalid timeout value

The certificate chain did not validate, no local certificate found

The certificate chain did not validate, common name did not match URL

Unexpected Request ID found in request

Required Request ID not found in request

Out of memory

Parameter list cannot be empty

Context initialization failed

Unexpected transaction state

Invalid name value pair request

Invalid response format


8



RESULT

-107

-108

-109

-111

-113

Description

This XMLPay version is not supported

The server certificate chain did not validate

Unable to do logging

The following error occurred while initializing from message file: <Details of the error message>

Unable to round and truncate the currency value simultaneously


A

Processors Requiring Additional

Transaction Parameters

Additional parameters are those required by individual processors beyond the core parameters.

Parameters are organized alphabetically by processor.





“American Express Additional Credit Card Parameters” on page 103

“Elavon Additional Credit Card Parameters” on page 109













“First Data Merchant Services Nashville, Additional Credit Card Parameters” on page 110

“First Data Merchant Services North, Additional Credit Card Parameters” on page 110

“Heartland, Additional Credit Card Parameters” on page 111

“Litle Additional Credit Card Parameters” on page 111

“Merchant e-Solutions, Additional Credit Card Parameters” on page 113

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

Express” on page 113









“PayPal Credit Card Transaction Request Parameters” on page 115

“SecureNet Additional Credit Card Parameters for American Express” on page 120

“Vantiv Additional Credit Card Parameters” on page 125

“WorldPay Additional Credit Card Parameters” on page 127

American Express Additional Credit Card Parameters

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

PayPal recommends that you include these parameters if you would like to impact what appears on AMEX statements and reports.

NOTE

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

Retail Transaction Advice Addendum (for SWIPE transactions)

Field

L_DESC n

Description

(Optional) Description of this line-item ( n is a line item number from 1 to 6).



A

Processors Requiring Additional Transaction Parameters

American Express Additional Credit Card Parameters

Field

L_AMT n

L_QTY n

Description

(Optional) Amount of this line-item ( n is a line item number from 1 to 6).

Character length and limitations: Must include a decimal and be exact to the cent

(42.00, not 42) and exclude comma separators (1234.56 not 1,234.56). Examples: tip=3.00, convenience charge=2.00. 12 numeric characters

(Optional) Quantity of this line-item ( n is a line item number from 1 to 6).


Internet Transaction Data

Field

BILLTOEMAIL

BILLTOPHONENUM

PHONETYPE

CUSTHOSTNAME

CUSTBROWSER

CUSTIP

SHIPTOCOUNTRY

SHIPMETHOD

SKU

Description

(Optional) Account holder’s email address.


(Optional) Account holder’s telephone number.


(Optional) Telephone company provided ANI information identifier digits indicating the telephone call type. Examples: cellular (61-63), payphone (27)


(Optional) Name of the server that the account holder is connected to. Example:

PHX.QW.AOL.COM

.

Character length and limitations: 60 alphanumeric and special characters

(Optional) Name of the server that the account holder is connected to. Example:

MOZILLA/4.0~(COMPATIBLE;~MSIE~5.0;~WINDOWS~95)


(Optional) Account holder’s IP address.


(Optional) Numeric country code of ship-to country. Example: USA: 840.


(Optional) Shipping method code. The values are:





01

= Same day

02

= Overnight/next day









03

= Priority, 2 - 3 days

04

= Ground, 4 or more days

05

= Electronic delivery

06

- ZZ = Reserved for future use

(Optional) Merchant product SKU.





A

Address Verification Service Parameters

Field

BILLTOSTREET

BILLTOZIP

BILLTOPHONENUM

SHIPTOFIRSTNAME

SHIPTOLASTNAME

SHIPTOSTREET

SHIPTOCOUNTRY

SHIPTOZIP

SHIPTOPHONENUM

Description

(Optional) Account holder’s street address (number and street name).


(Optional) Account holder’s 5- to 9-digit ZIP (postal) code excluding spaces, dashes, and non-numeric characters. Example: 951121737


(Optional) Account holder’s telephone number. The formats are:



 xxx-xxx-xxxx (US numbers)

+xxxxxxxxxxx (international numbers)


(Optional) First name in the shipping address.


(Optional) Last name in the shipping address.


(Optional) Shipping street address.




(Optional) Shipping 5- to 9-digit zip (postal) code excluding spaces, dashes, and non-numeric characters. Example: 951121737


(Optional) Shipping telephone number.


Location Transaction Advice Addendum Parameters

Field

MERCHANTNAME

MERCHANTSTREET

Description

(Optional) Name of merchant.


(Optional) Merchant’s street address (number and street name).

Character length and limitations: 38 alphanumeric characters. If more than 38 characters, use proper and meaningful abbreviation. Do not truncate.


A



Field

MERCHANTCITY

MERCHANTSTATE

MERCHANTZIP

Description

(Optional) The name of the city were the transaction took place.



If you are a third-party biller (bill for services or goods rendered by another entity), you must enter the name of the city in which the seller is located.



If you are a mail order, phone order, or internet industry, you may substitute the name of the city in which the merchant’s order processing facility is located.


(Optional) The region code that corresponds to the state, province, or country subdivision of the merchant location where the transaction took place.

Region code examples:







CA

= California, USA

NS

= Nova Scotia, Canada

COS

= Colima Mexico

If you are a third-party biller (bill for services or goods rendered by another entity), you must enter the region code that corresponds to the state, province, or country subdivision in which the seller is located.


(Optional) The 5- to 9-digit zip (postal) code excluding spaces, dashes, and nonnumeric characters where the transaction took place.

If you are a third-party biller (bill for services or goods rendered by another entity), you must enter the postal code that corresponds to the seller’s location.


MERCHANTCOUNTRYCODE

(Optional) Country code of the location where the transaction took place.


MERCHANTLOCATIONID

(Optional)Merchant-assigned store or location number (or name) that uniquely identifies where the transaction took place.


MERCHANTID

(Required) American Express-assigned service establishment number used to identify and facilitate payments to merchants.

Character length and limitations: 15 alphanumeric characters.

MERCHANTCONTACTINFO

(Optional) Merchant’s telephone number or web address. (URLs and e-mail addresses may be lowercase, as appropriate.) This entry may appear on the descriptive bill on the card-member’s statement, or may be used to resolve billing inquiries and disputes.

NOTE

: American Express strongly recommends that aggregators (third-parties who bill for goods or services rendered by another entity) always fill in this field with the URL, e-mail address, or telephone number of the contact responsible for resolving disputes or inquiries.





A

Transaction Advice Detail Parameters

Field

ADDLAMT n

ADDLAMTTYPE n

Description

(Optional) Detail of a charge where n is a value from 1 - 5. Use for additional breakdown of the amount.



(Optional) A 3-digit code indicating the type of the corresponding charge detail, where n is a value from 1 - 5.


Airline Passenger Data Parameters

Field

AIR-DEPARTUREDATE

AIR-PASSENGERNAME

Description

(Optional) Departure date in the format YYYYMMDD.


(Optional) Name of the passenger in the following format with fields separated by a space: surname firstname middleinitial title


AIR-ORIGIN

AIR-DESTINATION

(Optional) Airport code of the originating airport. For a list of airport codes, see http://www.world-airport-codes.com/alphabetical/airport-code/a.html

.

NOTE

: Present day airport codes are three characters in length. The five character length is designed to allow for future expansion


(Optional) Destination airport code for the first segment of the trip; this is not necessarily the final destination. For example, if a passenger flies from STL to MIA with a layover at JFK, the destination airport is JFK For a list of airport codes, see http://www.world-airport-codes.com/alphabetical/airport-code/a.html

.

NOTE

: Present day airport codes are three characters in length. The five character length is designed to allow for future expansion


AIR-NUMBEROFCITIES

(Optional) Number of unique cities in this trip including the cities of origin and destination, where a maximum value of 10 is allowed. For example, AIR-

NUMBEROFCITIES

is 3 for the following trip:



DEN to LAX





LAX to SFO

SFO to DEN

If not provided, this value is equal to the number of AIR-ROUTINGCITY n parameters.


A



Field

AIR-ROUTINGCITY

AIR-CARRIER n n

Description

(Optional) Airport codes of each city in this flight including cities of origin and destination, where n is a value from 1 to 10.


(Optional) Two character airline code for each unique airline in this flight, where n is a value from 1 to 10.

If the same carrier is used for multiple segments of the trip, it is passed only once. For example, the two AIR-CARRIER n values for the following trip are UA and AA:





UA flight from IAD to DEN

UA flight from DEN to LAX





UA flight from LAX to SFO

AA flight from SFO to DFW

For information about airlines codes, see http://en.wikipedia.org/wiki/Airline_codes-

All


AIR-FAREBASIS

AIR-

NUMBEROFPASSENGERS

(Optional) List discounts associated with the travel.


(Optional) Number of passengers on this trip.

Character length and limitations: numeric

AIR-ISETICKET

(Optional) If this is an electronic ticket. The values are:

 Y

= yes

 N

= no

Character length and limitations: 1 alphanumeric character

AIR-RESERVATIONCODE

(Optional) Code assigned to the travel reservation before the ticket was purchased.


American Express Other Parameters

Field

BILLTOFIRSTNAME

BILLTOLASTNAME

Description

(Optional) Account holder's first and last name.

NOTE

: Even though the parameter name indicates only the first name, this single parameter holds all of the person's name information (both first and last name, at a minimum).


(Optional) Account holder's last name.



Field

INVNUM

ORDERDATE

ORDERDATETIME


Elavon Additional Credit Card Parameters

A

Description

(Optional) Merchant invoice number. The merchant invoice number is used for authorizations and settlements and, depending on your merchant bank, will appear on your customer's credit card statement and your bank reconciliation report. If you do not provide an invoice number, the transaction ID (PNREF) will be submitted.


(Optional) Specifies an order date.


Format: mmddyy (with no slashes or dashes). For example, July 28, 2003 is 072803.

(Optional) Specifies an order time and date.


Format is either YYYY-MM-DD or YYYY-MM-DD HH:MI:SS

(where HH is in 24-hour time). If the value does not conform to one of the formats or if the date is not valid (for example, 2004-17-35), then the transaction is rejected with: RESULT=7(SIG_FIELD_ERR) RESPMSG=Invalid ORDERTIME

A truncated version of the ORDERTIME value (up to 7 characters) overwrites any value provided by ORDERDATE. If no value is provided, a NULL value is stored.

Elavon Additional Credit Card Parameters

In addition to the core credit card parameters, Elavon (formerly Nova) accepts the parameter described below.

Field

RECURRING

Description

(Optional) Identifies the transaction as recurring. This value does not activate the

Payflow Recurring Billing Service API.

If the RECURRING parameter was set to Y for the original transaction, then the setting is ignored when forming credit, void, and force transactions.

If you subscribe to Payflow Fraud Protection Services:



To avoid charging you to filter recurring transactions that you know are reliable, the fraud filters do not screen recurring transactions.



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

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

Character length and limitations: 1 alphanumeric character (Y or N)


110

A


First Data Merchant Services Nashville, Additional Credit Card Parameters

First Data Merchant Services Nashville, Additional Credit Card

Parameters

In addition to the core credit card parameters, First Data Merchant Services (FDMS) Nashville accepts the parameters described below.

Field

INVNUM

Description

(Optional) Merchant invoice number. The merchant invoice number is used for authorizations and settlements and, depending on your merchant bank, will appear on your customer's credit card statement and your bank reconciliation report. If you do not provide an invoice number, the transaction ID (PNREF) will be submitted.


First Data Merchant Services North, Additional Credit Card

Parameters

In addition to the core credit card parameters, First Data Merchant Services (FDMS) North accepts the parameters described

Field

DESC

MERCHDESCR

Description

(Optional) Use the DESC* parameters to pass in your DBA name and other data describing the transaction. This information will be displayed in the account holder’s statement.

NOTE

: Note: FDMS North passes the descriptive data to the card associations with the following character lengths:

Visa: 25

MasterCard: 22

AMEX: 20

DISC: 22

Some card associations truncate the value to 19 characters. If you have questions, consult the card association.


(Optional) Use this parameter to pass in your DBA name and other data describing the transaction. This information is usually displayed in the account holder’s statement.



Field

MERCHSVC


Heartland, Additional Credit Card Parameters

A

Description

(Optional) Defaults to the city where the merchant outlet is located for retail and to the merchant’s phone number for non-retail. For example, 800 111-1111. This information is usually displayed in the account holder’s statement.


Heartland, Additional Credit Card Parameters

In addition to the core credit card parameters, Heartland accepts the parameters described below.

Field

INVNUM

MERCHDESCR

MERCHSVC

Description


NOTE

: Not supported by Payflow Link.


(Optional) Use this parameter to pass in your DBA name and other data describing the transaction (default: merchant name). This information is usually displayed in the account holder’s statement.




Litle Additional Credit Card Parameters

Field

AUTHDATE

CUSTOMERID

Description

Required for Force transactions. Authorization date.

Character length and limitations: 11alphanumeric characters

(Optional) Customer identification.



112

A


Litle Additional Credit Card Parameters

Field

INVNUM

MERCHANTCITY

MERCHANTURL

MERCHDESCR

MERCHSVC

PONUM

REPORTGROUP

BILLTOSTREET2

BILLTOSTREET3

TAXAMT

TAXEXEMPT

Description

(Optional) Merchant invoice number. The merchant invoice number is used for authorizations. If you do not provide an invoice number, the transaction ID (PNREF) will be submitted.










(Optional) Merchant’s website. This information is usually displayed in the account holder’s statement.






(Optional) Purchase order number.


(Optional) Category that the transaction is in, for example, coffee mugs. This field is for your own use.


(Optional) Second street address.


(Optional) Third street address.


(Optional) Total tax amount.



(Optional) Indicates whether the customer is tax exempt. It is one of the following values:

 Y

– The customer is tax exempt.

 N

– The customer is not tax exempt (default).




Merchant e-Solutions, Additional Credit Card Parameters

A

Merchant e-Solutions, Additional Credit Card Parameters

In addition to the core credit card parameters, Merchant e-Solutions accepts the parameters described below.

Field

INVNUM

MERCHDESCR

MERCHSVC

Description


NOTE

: Not supported by Payflow Link.


(Optional) Use this parameter to pass in your DBA name and other data describing the transaction (default: merchant name). This information is usually displayed in the account holder’s statement.




Paymentech Salem (New Hampshire) Additional Credit Card

Parameters for American Express

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

Internet Transaction Data Parameters

Field

BILLTOEMAIL

BILLTOPHONENUM

PHONETYPE

Description

(Optional) Account holder’s email address.


(Optional) Account holder’s telephone number.


(Optional) Telephone company provided ANI information identifier digits indicating the telephone call type. Examples: cellular (61-63), payphone (27)



114

A


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

Field

CUSTHOSTNAME

CUSTBROWSER

CUSTIP

SHIPTOCOUNTRY

SHIPMETHOD

SKU

Description

(Optional) Name of the server that the account holder is connected to. Example:

PHX.QW.AOL.COM

.





(Optional) Account holder’s IP address.


(Optional) Numeric country code of ship-to country. Example: USA: 840.


(Optional) Shipping method code. The values are:

 01

= Same day





02


03








04


05


06

- ZZ = Reserved for future use

(Optional) Merchant product SKU.


AVS Parameters

Field

BILLTOSTREET

BILLTOZIP

BILLTOPHONENUM

SHIPTOFIRSTNAME

SHIPTOLASTNAME

Description

















PayPal Credit Card Transaction Request Parameters

A

Field

SHIPTOSTREET

SHIPTOCOUNTRY

SHIPTOZIP

SHIPTOPHONENUM

Description









Additional Credit Card Parameters for M Record

Field

MERCHDESCR

MERCHSVC

Description





PayPal Credit Card Transaction Request Parameters

In addition to the core credit card parameters, PayPal accepts the parameters described below.

Parameter

ACCTTYPE

Description

(Optional) Credit card type. The following card types are supported:





0

= Visa

1

= MasterCard











2

= Discover

3

= AMEX

4

= DinersClub

5

= JCB

8

= Other


116

A



Parameter

AMT

CURRENCY

BUTTONSOURCE

CUSTIP

CAPTURECOMPLETE

CUSTOM

EMAIL

INVNUM

Description

(Required) Amount (US Dollars) U.S. based currency.

AMT=ITEMAMT + TAXAMT + FREIGHTAMT + HANDLINGAMT + INSURANCEAMT

- DISCOUNT

NOTE

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

Limitations: Must not exceed $10,000 USD in any currency. Nine numeric characers plus decimal (.) character. No currency symbol. Specify the exact amount to the cent using a decimal point—use 34.00, not 34. Do not include comma separators—use

1199.95 not 1,199.95.

Nine numeric characters plus decimal.

(Required) The currency code.

NOTE

:

CURRENCY

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

Limitations: Three characters.

(Optional) Identification code for use by third-party applications to identify transactions.

Limitations: 32 alphanumeric characters.

(Optional) IP address of payer’s browser as recorded in its HTTP request to your website. This value is optional but recommended.

NOTE

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

Limitations: 15-character string in dotted quad format: xxx.xxx.xxx.xxx

(Optional) Indicates if this Delayed Capture transaction is the last capture you intend to make. The values are:

 Y

(default)

 N

NOTE

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

Limitations: 12-character alphanumeric string.

(Optional) A free-form field for your own use.

Limitations: 256-character alphanumeric string.

(Optional) Email address of payer.


(Optional) Your own unique invoice or tracking number.



Parameter

ITEMAMT

TAXAMT

FREIGHTAMT

HANDLINGAMT

DISCOUNT

INSURANCEAMT



A

Description

(Required if L_COST n is specified) Sum of cost of all items in this order.

ITEMAMT = L_QTY0*LCOST0 + L_QTY1*LCOST1...L_QTY

n*L_COST n

Limitations: Nine numeric characers plus decimal (.) character. No currency symbol.

Specify the exact amount to the cent using a decimal point—use 34.00, not 34. Do not include comma separators—use 1199.95 not 1,199.95.

Limitations: Nine numeric characters plus decimal.

(Required if L_TAXAMT n is specified) Sum of tax for all items in this order.

TAXAMT=L_QTY0*L_TAXAMT0 + L_QTY1*L_TAXAMT1 +...L_QTY

n

*L_TAXAMT n

NOTE





(Optional) Total shipping costs for this order.

NOTE





(Optional) Total handling costs for this order.

NOTE





(Optional) Shipping discount for this order. Specify the discount as a positive amount.



(Optional) Total shipping insurance cost for this order.




118

A



Parameter

L_NAME

L_DESC

L_COST

L_QTY

L_SKU n n n n n

L_TAXAMT n

MERCHANTSESSIONID

Description

(Optional) Line-item name.

NOTE

: To enable line-item support, you must contact Merchant Technical Support at http://www.paypal.com/mts


(Optional) Line-item description of the item purchased such as hiking boots or cooking utensils

.

NOTE



(Required if L_QTY n is supplied) Cost of the line item. The line-item unit price can be a positive or a negative value but not 0.

NOTE


NOTE





(Required if L_COST n is supplied) Line-item quantity.

NOTE


Limitations: 10-character integer.

(Optional) Product number.

NOTE


Limitations: 18-characters.

(Optional) Line-item tax amount.

NOTE




(Optional) Your customer Direct Payment session identification token.

PayPal records this session token as an additional means to detect possible fraud.

Limitations: 64 characters.


Parameter

NOTIFYURL

ORDERDESC

RECURRINGTYPE

BILLTOCITY

BILLTOSTATE

BILLTOCOUNTRY

SHIPTOSTREET

SHIPTOCITY



A

Description

(Optional) Your URL for receiving Instant Payment Notification (IPN) about this transaction. If you do not specify NOTIFYURL in the request, the notification URL from your Merchant Profile is used, if one exists.


(Optional) Description of items the customer is purchasing.


(Optional) Type of transaction occurrence. The values are:

 F

= First occurrence

 S

= Subsequent occurrence (default)

Limitations: One alpha character.

(Conditional) Bill-to city address.


NOTE

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

(Conditional) Bill-to state or province address.


NOTE


(Conditional) Bill-to country address.


NOTE


(Optional) Ship-to street address.

NOTE

: If you pass in any of the ship-to address parameters such as SHIPTOCITY or

SHIPTOSTATE

, you must pass in the complete set (that is, SHIPTOSTREET,

SHIPTOCITY

, SHIPTOSTATE, SHIPTOCOUNTRY, and SHIPTOZIP).


(Optional) Ship-to city address.

NOTE


SHIPTOSTATE


SHIPTOCITY




A


SecureNet Additional Credit Card Parameters for American Express

Parameter

SHIPTOSTATE

SHIPTOCOUNTRY

SHIPTOZIP

Description

(Optional) Ship-to state or province address.

NOTE


SHIPTOSTATE


SHIPTOCITY



(Optional) Ship-to country code.

NOTE


SHIPTOSTATE


SHIPTOCITY


Limitations: Two alpha characters.

(Optional) U.S. ship-to zip code or other country-specific postal code.

NOTE


SHIPTOSTATE


SHIPTOCITY



SecureNet Additional Credit Card Parameters for American

Express

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

Retail Transaction Advice Addendum (for SWIPE transactions)

Field

L_DESC n

L_AMT n

L_QTY n

Description

(Optional) Description of this line-item ( n is a line item number from 1 to 6).


(Optional) Amount of this line-item ( n is a line item number from 1 to 6).



(Optional) Quantity of this line-item ( n is a line item number from 1 to 6).





A

Internet Transaction Data

Field

BILLTOEMAIL

BILLTOPHONENUM

PHONETYPE

CUSTHOSTNAME

CUSTBROWSER

CUSTIP

SHIPTOCOUNTRY

SHIPMETHOD

Description

(Optional) Account holder’s email address.


(Optional) Account holder’s telephone number.


(Optional) Telephone company provided ANI information identifier digits indicating the telephone call type. Examples: cellular (61-63), payphone (27).



PHX.QW.AOL.COM

.





(Optional) Account holder’s IP address.


(Optional) Numeric country code of ship-to country. Example: USA: 840.


(Optional) Shipping method code. The values are:

 01

= Same day





02


03








04


05


06 - ZZ

= Reserved for future use

AVS Parameters

Field

BILLTOSTREET

BILLTOZIP

Description






A



Field

BILLTOPHONENUM

SHIPTOFIRSTNAME

SHIPTOLASTNAME

SHIPTOSTREET

SHIPTOCOUNTRY

SHIPTOZIP

SHIPTOPHONENUM

Description




















Parameter

MERCHANTNAME

MERCHANTSTREET

MERCHANTCITY

Description
















A

Parameter

MERCHANTSTATE

Description



 CA

= California, USA





NS


COS

= Colima Mexico



MERCHANTCOUNTRYCODE



MERCHANTZIP



Character length and limitations; 15 alphanumeric characters


Field

ADDLAMT n

ADDLAMTTYPE n

Description






Airline Passenger Data Parameters

Field

AIR-DEPARTUREDATE

AIR-PASSENGERNAME

Description

(Optional) Departure date in the format: YYYYMMDD.


(Optional) Name of the passenger in the following format with fields separated by a space: surname firstname middleinitial title



A



Field

AIR-ORIGIN

AIR-DESTINATION

Description

(Optional) Airport code of the originating airport. For a list of airport codes, see http://www.world-airport-codes.com/alphabetical/airport-code/a.html.

NOTE

: Present day airport codes are three characters in length. The five character length is designed to allow for future expansion.


(Optional) Destination airport code for the first segment of the trip; this is not necessarily the final destination. For example, if a passenger flies from STL to MIA with a layover at JFK, the destination airport is JFK. For a list of airport codes, see http://www.world-airport-codes.com/alphabetical/airport-code/a.html.

NOTE



AIR-NUMBEROFCITIES

(Optional) Number of unique cities in this trip including the cities of origin and destination, where a maximum value of 10 is allowed. For example, AIR-

NUMBEROFCITIES

is 3 for the following trip:



DEN to LAX





LAX to SFO

SFO to DEN

If not provided, this value is equal to the number of AIR-ROUTINGCITY n parameters.

Character length and limitations: numeric, maximum value is 10

AIR-ROUTINGCITY n (Optional) Airport codes of each city in this flight including cities of origin and destination, where n is a value from 1 to 10. For a list of airport codes, see http://www.world-airport-codes.com/alphabetical/airport-code/a.html.

NOTE



AIR-CARRIER n (Optional) Two character airline code for each unique airline in this flight, where n is a value from 1 to 10. If the same carrier is used for multiple segments of the trip, it is passed only once. For example, the two AIR-CARRIER n values for the following trip are UA and AA:





UA flight from IAD to DEN

UA flight from DEN to LAX





UA flight from LAX to SFO

AA flight from SFO to DFW

For information about airlines codes, see http://en.wikipedia.org/wiki/Airline_codes-

All.


AIR-FAREBASIS

(Optional) List discounts associated with the travel.




Vantiv Additional Credit Card Parameters

A

Field

AIR-

NUMBEROFPASSENGERS

AIR-ISETICKET

Description

(Optional) Number of passengers on this trip.


(Optional) If this is an electronic ticket.

Character length and limitations: 1 alphanumeric character (Y or N)

AIR-RESERVATIONCODE

(Optional) Code assigned to the travel reservation before the ticket was purchased.


Other Parameters

Field

BILLTOFIRSTNAME

BILLTOLASTNAME

INVNUM

ORDERDATE

Description

(Optional) Account holder's first and last name.

NOTE

: Even though the parameter name indicates only the first name, this single parameter holds all of the person's name information (both first and last name, at a minimum).


(Optional) Account holder's last name.




(Optional) Specifies an order date.


Format: mmddyy (with no slashes or dashes). For example, July 28, 2003 is 072803.

Vantiv Additional Credit Card Parameters

Additional Credit Card Parameters

Field

MERCHDESCR

Description

(Optional) Use this parameter to pass in your DBA name and other data describing the transaction. This information will be displayed in the account holder’s statement.



A


Vantiv Additional Credit Card Parameters

Soft Merchant Descriptor Parameters

Field

MERCHANTNAME

MERCHANTSTREET

MERCHANTCITY

Description













MERCHANTSTATE



 CA

= California, USA





NS


COS

= Colima Mexico



MERCHANTZIP




MERCHANTCOUNTRYCODE



MERCHANTLOCATIONID



MERCHANTID





WorldPay Additional Credit Card Parameters

A

Field Description

MERCHANTCONTACTINFO


NOTE



WorldPay Additional Credit Card Parameters

Field

ADDLAMT n

ADDLAMTTYPE n

CATTYPE

CONTACTLESS

Description

(Optional) Detail of a charge, where n is a value from 1 - 5. Use for additional breakdown of the amount.




(Optional) Type of terminal.

Character length and limitations: numeric characters

(Optional) Describes the card input capability. It is the value RFD, which means the card contains a radio frequency identification (RFID) chip for communicating with a point-of-sale device with an RFID receiver.

Character length and limitations: alpha characters


A


WorldPay Additional Credit Card Parameters


B

TeleCheck Electronic Check

Processing

This appendix describes the host-based capture version of the TeleCheck Non-Face-To-Face

Check Acceptance (NFTF) services.

TeleCheck NFTF Overview of Services

NFTF offers merchants the convenience of electronic check deposits. When a NFTF transaction is approved by TeleCheck, the manually entered MICR data from the check is electronically converted to an ACH debit and is processed through the ACH Network. The merchant receives funds within two banking days.

NFTF includes TeleCheck Internet Check Acceptance (ICA), Checks By Phone (CBP), and

Prearranged Deposit Services (NFTF PPD). Each of these products requires a separate

Merchant ID also known as a Subscriber ID. See below for more details.







ICA provides merchants with the capability to authorize and electronically settle checks presented by customers over the internet. ICA can be single entry or recurring. This is based on customer's authorization received over the internet.

CBP authorizes and electronically settles checks presented over the phone through customer interaction with a merchant call center representative. CBP services are single entry only. Partial debits and recurring entries are not allowable per NACHA guidelines.

NFTF prearranged payment and deposit entry (NFTF PPD) may be used for either recurring or non-recurring debits to a customer's account, when the merchant has provided the customer with a written authorization, which the customer has signed or similarly authenticated. Actual payments are facilitated via the internet or via IVR or over the phone.

The application type value must be set to PPD. PPD accounts must establish an end date to clearly define terms between customer and merchant, but do not have time period caps.

TeleCheck NFTF Processing Overview

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

NFTF Requirements

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



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


B

TeleCheck Electronic Check Processing

TeleCheck NFTF Processing Overview

























Dual ID is required for all transactions. For personal checks, it must be MICR data and personal check writer identification such as a driver’s license. For company checks, it must be MICR data and Federal Tax ID. In the event that a company does not have a Federal Tax

ID, the driver’s license can also be used.

For ICA and NFTF PPD, the merchant must retain the customer’s authorization of the transaction for a period of 2 years and, for ICA, prompt the customer to print a copy of this confirmation for their records. The merchant must adhere to all authorization requirements, data elements, legal verbiage, and check return fee requirements.

For CBP, the merchant must audio record the customer’s verbal confirmation of the transaction or provide a written confirmation of the transaction to the customer prior to settlement. In either case, the confirmation must be live; IVR is not acceptable for confirmation. If a merchant chooses audio, the merchant must have the technical capability to retain these recordings for a period of 2 years; else the written confirmation may be substituted and retained for the same time period. The merchant must adhere to all authorization requirements; data elements, legal verbiage, and check return fee requirements.

Only select US accounts drawn on U.S. banks participating in the ACH Network are eligible for processing via the ACH Network.

TeleCheck Trace ID (TTID) is required for all supplemental messages, change, void, and adjustment transactions.

Merchant Trace ID is required for all adjustment transactions. This field allows additional capabilities to be enabled such as Overflow Credits and MIA Duplicate Checking.

Change and Void transactions are only allowed within the original Sale processing window.

For NFTF, cutoff time is 4:00PM CST (recommend working with 3:30PM CST).

Adjustment transactions are electronically allowed within 90 days after the Sale transaction. After the 90 day period, all adjustments must be manually processed.

A prompt or process must be in place to identify a check as either personal or company.

Duplicate Checking – TeleCheck has the ability to detect duplicate sale transactions at the point of sale if sent within a predetermined time limit. Duplicates are identified when a sale inquiry is received with the same amount, MICR number, and check number matching a sale inquiry received within the last 2 minutes. If a duplicate is detected it will return an ineligible response for ACH. The 2nd transaction will also receive an ineligible response for ACH with the same ACH Transaction Status and Response Code as the original sale transaction.

The appropriate Application Type value must be sent to TeleCheck to indicate the type of

NFTF transaction (ICA, CBP, or NFTF PPD).

In the NFTF technical specification several data element fields and features are described as “optional.” While these are technically optional, meaning that the product can be technically implemented with or without them, TeleCheck may require the merchant to code to one or more of these optional items based on the agreed upon contractual terms.

The merchant may need to account for and enable additional data element fields and product features in their system(s) and in communications to TeleCheck’s Authorization



TeleCheck NFTF Processing Overview

B



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

First Data Gateway Partners, External Gateway vendors, First Data Platforms, and the

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

NFTF Processing Considerations

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



MIA Duplicate Checking – TeleCheck has the ability to detect duplicate adjustment transactions in back end processes. Adjustments can be submitted up to 90 days after the original Sale transaction. While multiple adjustment transactions are allowed for a given sale transaction, each adjustment transaction must have a unique merchant trace ID.

Duplicates are detected when an adjustment transaction is submitted that has the same merchant trace ID as a previously submitted adjustment transaction. If a duplicate adjustment is detected, and the original adjustment was accepted by TeleCheck, the duplicate will also be accepted. The duplicate transaction will then be filtered out by

TeleCheck’s back end settlement processes.

NFTF Guidelines

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





Fields marked as Required are required to process an electronic transaction.

Not all fields are required by every merchant.











Unused fields should be completely omitted from the message.

Each field is variable in length (justification and fillers are not used).

The order of tagged fields from the POS and from the TeleCheck host are not significant.

Fields must not have any hard-coded data values.

The transaction number increments on every attempt.

Message formats outline fields (tags) that are required, not required, or conditional to the Sale,

Status, and Adjustment Inquiry packets.

Message Types:



Merchant Authorization Message and the TeleCheck Authorization Response Message



Merchant Delayed Capture Message and the TeleCheck Delayed Capture Response

Message


B


TeleCheck Parameters

Transaction flow Method

Messages sent from the Merchant to TeleCheck are authorization messages. Messages sent from TeleCheck to the Merchant are Response messages.

The sale transaction process is often referred to as a 2-part hand-off. The process begins with the merchant’s Authorization message. TeleCheck responds with an Authorization response message indicating whether the transaction is approved and whether the check is eligible for conversion (whether check conversion will be offered). The Merchant then responds with a

Delayed Capture message, acknowledging receipt of TeleCheck’s sale response, and indicating whether electronic check conversion was accepted. TeleCheck completes the transaction with a Delayed Capture response message confirming receipt of the merchant’s status inquiry message.

132

TeleCheck Parameters

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




B

Required TeleCheck Parameters

Field

USER

VENDOR

PARTNER

PWD

AMT

AUTHTYPE

BILLTOCITY

BILLTOCOUNTRY

BILLTOFIRSTNAME

BILLTOLASTNAME

Description

(Required) Case-sensitive login ID for the Gateway account that you created while registering for the account.

In the future, each account will allow multiple users. This parameter will specify the user.


(Required) Case-sensitive Vendor ID that you created while registering for the account.


(Required) The authorized PayPal Reseller that registered you for the Gateway service provided you with a Partner ID. If you registered yourself, use PayPal.

This parameter is case sensitive.


(Required) Case-sensitive 6- to 32-character password that you created while registering for the account.


(Required) This is the transaction amount (default U.S. dollars).

The transaction amount should always specify a decimal, and the exact amount to the cent (for example, 34.00, instead of 34). Do not include comma separators in the amount. Use 1199.95 not 1,199.95.

Character length and limitations: 7 numeric characters, U.S. dollars only

It is one of the following values:

 I

– Internet Check Acceptance (ICA) provides the capability to authorize and electronically settle checks over the intenet.





P

– Checks By Phone (CBP) provides the capability to authorize and electronically settle checks over the phone.

D

– Prearranged Deposit Services (PPD) debits the customer’s account provided the customer has previously accepted a written authorization.

(Required) Account holder’s city.


Account holder’s country. You are required to pass this value when AUTHTYPE=I.


Account holder’s first name as it appears on the check. You are required to pass this value when CHKTYPE=C.


(Required) Account holder’s last name as it appears on the check.



B



Field

BILLTOPHONENUM

BILLTOSTATE

BILLTOSTREET

BILLTOZIP

CHKNUM

CHKTYPE

CUSTIP

DL

BILLTOEMAIL

INVNUM

MICR

Description

(Required) Account holder’s telephone number.

Character length and limitations: 10 numeric characters. This value may not contain spaces or non-numeric characters.

(Required) Account holder’s state.


(Required) Account holder’s street address.


(Required) Account holder’s postal code (called ZIP code in the USA). Do not use spaces, dashes, or non-numeric characters.


(Required) Account holder’s next unused (available) check number.


(Required) Check type. It is one of the following values:





P

– The check is a personal check (default). If CHKTYPE=P, you are required to pass a value for either DL or SS as an identifier.

C

– The check is a company check. If CHKTYPE=C, you are required to pass the

Federal Tax ID for SS.

Character length and limitations:1 alphanumeric character

Account holder’s IP address. You are required to pass this value when AUTHTYPE=I.


(Required) Driver’s license number. If CHKTYPE=P, you are required to pass a value for either DL or SS as an identifier.

The format of the driver’s license is XXnnnnnnnn where:





XX

– State code nnnnnnnn

– Driver’s license number


Account holder’s e-mail address. You are required to pass this value when

AUTHTYPE=I

.


(Optional) Check invoice number.


(Required) Magnetic ink check reader. The value is the entire line of numbers at the bottom of all checks. It includes the transit number, account number, and check number.



Field

SS

TENDER

TRXTYPE


Testing TeleCheck Transactions

B

Description

Account holder’s social security number. You are required to pass a value for SS when a value for CHKTYPE is passed:



If CHKTYPE=P, you are required to pass a value for either DL or SS as an identifier.



If CHKTYPE=C, you are required to pass the Federal Tax ID.


(Required) Method of payment. Use only the value K (electronic check).

Character length and limitations: 1 alphabetic character

(Required) Type of transaction that should be processed. It is one of the following values:

 A

– The transaction is an Authorization.







D

– The transaction is a Delayed Capture.

V

– The transaction is a Void.

I

– The transaction is an Inquiry.


Testing TeleCheck Transactions

PayPal provides a test server to support testing and configuration. For information on the test

server URL, see “Host URL Addresses” on page 42 .

Example Test Transaction

This is the authorization request and response.

TRXTYPE=A&TENDER=K&PARTNER=partner&USER=user&VENDOR=vendor&PWD=pwd&AMT=35.0

0&BILLTOSTREET=1234 Main&BILLTOCITY=Buffalo&DL=CA123456&CHKNUM=1001&BILLTOE

[email protected]&MICR=3333333333&AUTHTYPE=I&INVNUM=12345&BILLTOFIRSTNAME=S ally&BILLTOLASTNAME=Smith&BILLTOSTATE=CA&BILLTOZIP=95050&BILLTOCOUNTRY=US&C

USTIP=10.15.5.23&BILLTOPHONENUM=9876542143&VERBOSITY=HIGH RESULT=0&PNREF=EQ

RB8A32CD69&RESPMSG=Approved&AUTHCODE=12&TRACEID=1234567890&ACHSTATUS=A&HOST

CODE=07&TRANSTIME=2012-02-

09 15:23:37&BILLTOFIRSTNAME=Sally&BILLTOLASTNAME=Smith&AMT=35.00&CARDTYPE=P

This is the delayed capture request and response.

TRXTYPE=D&TENDER=K&PARTNER=partner&USER=user&VENDOR=vendor&PWD=pwd&ORIGID=E

QRB8A32CD69&VERBOSITY=HIGH

RESULT=0&PNREF=EQRB8A32CD6A&RESPMSG=Approved&AUTHCODE=00&TRACEID=1234567890

&ACHSTATUS=A&HOSTCODE=07&TRANSTIME=2012-02-09 15:24:22


B


Preparing for TeleCheck Production Transactions

MICR

3333333333

1111111111

2222222222

MICR values for testing

You may view a complete list of TeleCheck response codes at

“Sale Response Code Values” on page 137

HOSTCODE

07

08

88

TeleCheck Result

Approved

Rejected (negative data)

Rejected Code 3 (Risk)

Preparing for TeleCheck Production Transactions

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

. Be sure to include the following information:



Your test website address where test transactions can be processed



The name, e-mail address, and phone number of the person to contact about any needed corrections.

The certification process usually takes 2-3 days.

Use the host address of the live server described in “Host URL Addresses” on page 42

.

136

Responses to TeleCheck Transactions

When a transaction finishes, PayPal returns a response string made up of name-value pairs.

For example:

RESULT=0&PNREF=VXYZ01234567&HOSTCODE=000500&RESPMSG=Approved

TeleCheck transaction response values are described in the table below.

Transaction Responses Common to All Tender Types

Field

RESULT

PNREF

Description

The outcome of the attempted transaction. A result of 0 (zero) indicates the transaction was approved. Any other number indicates a decline or error.

Character length and limitations: numeric, variable number of characters

PayPal Reference ID, a unique number that identifies the transaction.



Field

HOSTCODE

RESPMSG


Response Code Values

B

Description

TeleCheck’s response code representing the results of the transaction authorization attempt.


A descriptive message associated with decline or error result values.

Character length and limitations: alphanumeric, variable number of characters

Response Code Values

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

NOTE

: Merchants should establish policies and procedures for each applicable response code.

For example, if a clerk enters a transaction and receives Response Code 27, they should retry the transaction. If, after entering the item a second time they receive a

Response Code 27 again, the merchant may choose to cancel or terminate the transaction and a) retry the transaction b) call TeleCheck Live Operator Authorization

Center, or c) request another form of payment from the check writer.

Sale Response Code Values

Sale Approval Responses

Code

07

Description

Approved

Merchant Action

No action needed.

Sale Decline Responses

Code

08

73

88

25

Description

Rejected (Negative Data)

Lost or Stolen check

Rejected Code 3 (Risk)

Ineligible – ACH Not Offered

NOTE

: Do NOT use the verbiage

“decline” this is not a true decline.

Merchant Action

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



Ask for other form of payment.


B


Response Code Values

Sale Referral Responses

Code

09

69

Description

Risk Referral requested

Call Center

Merchant Action

Contact TeleCheck.

Contact TeleCheck.

49

98

27

78

97

Sale Error Responses

Code

46

Description

Merchant setup does not allow this type of transaction

Processor Not Available

Invalid MICR Data

Invalid Value for Field

Invalid RT (Routing/Bank Number)

Unable to Process (Time Out)

Merchant Action

Re-send message later.

Re-send message later.

Adjustment Code Values

Adjustment (Refund/Change/Void) Responses

Code

26

46

79

Description

Merchant allowed to send full/partial adjustments/refunds without transaction errors

Merchant setup does not allow this type of transaction

Original transaction was not approved

80

81

Refund or partial amount is greater than the original sale amount

Unable to locate original transaction

(TCK Trace ID)

Merchant Action

No action needed

Adjustment cannot be processed by

TeleCheck


TeleCheck


TeleCheck


TeleCheck

Response Codes For Status Response Packets

Response Codes for Status Response Packets

Code

OK

Description

Inquiry (POS system) Packet was accepted and successfully processed by TeleCheck


49

97

27

Code

ACK

NAK


TeleCheck Authorization Requirements

B

Description

Inquiry Packet was accepted by the TeleCheck Host

Inquiry Packet was not successfully processed by TeleCheck (general error)

Inquiry Packet was not successfully processed by TeleCheck (scheduled maintenance)

Inquiry Packet was not successfully processed by TeleCheck (timeout)

Inquiry Packet was not successfully processed by TeleCheck (invalid data)

TeleCheck Authorization Requirements

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

NOTE

: It is the merchant’s responsibility to ensure that they have the most current language from TeleCheck. TeleCheck will send out a Service Notice when updated language or system changes are required. Additionally, the Merchant should be familiar with

NACHA, FCRA and Reg. E compliance requirements.

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



Authorization – Sales Consent

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



Authorization – Sales Decline

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

Authorization – Sales Consent

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

Internet Check Acceptance Authorizations

At the end of the check out process, the merchant must display consent language for the customer to accept prior to submitting the authorization request as follows:

Internet Check Acceptance Authorization Consent Required Language

FULL DEBIT

By entering my account number above and clicking Authorize, I authorize my payment to be processed as an electronic funds transfer or draft drawn from my account. If the payment is returned unpaid, I authorize you or your service provider to collect the payment and my state’s


B


TeleCheck Authorization Requirements return item fee by electronic funds transfer(s) or draft(s) drawn from my account. Click here

to view your state’s returned item fee. If this payment is from a corporate account, I make these authorizations as an authorized corporate representative and agree that the entity will be bound by the NACHA Operating Rules.

PARTIAL SHIPMENTS & PARTIAL DEBITS

By entering my account number above and clicking Authorize, I authorize my payment to be processed as an electronic funds transfer or draft drawn from my account. If my full order is not available at the same time, I authorize partial debits to my account, not to exceed the total authorized amount. The partial debits will take place upon each shipment of partial goods. If any of my payments are returned unpaid, I authorize you or your service provider to collect the payment and my state’s return item fee by electronic fund transfer(s) or draft(s) drawn from my account. Click here to view your state’s returned item fee. If this payment is from a corporate account, I make these authorizations as an authorized corporate representative and agree that the entity will be bound by the NACHA Operating Rules.

Internet Check Acceptance Recurring Payments (WEB R)

By entering my account number above and clicking Authorize, I authorize my payments to be processed as electronic funds transfers or drafts drawn from my account. {INSERT

INFORMATION ON PAYMENT AMOUNT, TIMING, ETC.} If any of my payments are returned unpaid, I authorize you or your service provider to collect the payment and my state’s return item fee by electronic fund transfer(s) or draft(s) drawn from my account. Click here

to view your state’s returned item fee. If this payment is from a corporate account, I make these authorizations as an authorized corporate representative and agree that the entity will be bound by the NACHA Operating Rules. This authorization is to remain in full force and effect until {NAME OF MERCHANT} has received written notification from me of my termination in such time and manner as to afford {NAME OF MERCHANT} a reasonably opportunity to act on it.

This text, Click here to view your state’s returned item fee, in the consent language above represents a link to the state fee table. TeleCheck has posted a table of current state returned check fees at http://www.firstdata.com/support/telecheck_returned_check/returned_check_fees.htm. The merchant should link directly to the TeleCheck-hosted URL provided above. State fees are updated on a regular basis and linking to a TeleCheck-hosted page will minimize the number of maintenance updates required. The merchant may choose how to display the state fees.

Suggestions include a new pop-up window, a full browser window, or directly on the checkout page.

Checks By Phone Service Authorizations

At the end of the check out process, the customer service agent must read the consent language to the consumer and, either audio record the consumer’s authorization or send a written notification of the authorization and the transaction to the consumer prior to settlement of the transaction. The consent language for the customer to accept prior to submitting the payment authorization request is as follows:

Checks By Phone Authorization Consent Required Language

FULL DEBIT



TeleCheck Authorization Requirements

B

Today (insert today’s date), I’d like to confirm that you, (insert first and last name), are authorizing a payment in the amount of (insert amount) to be processed as an electronic funds transfer or draft drawn from your account. Do you agree? If your payment is returned unpaid, you authorize us or our service provider to collect the payment and your state’s return item fee of (insert state returned item fee) by electronic funds transfer(s) or draft(s) drawn from your account. Do you agree and authorize the payment?

The merchant should link directly to the TeleCheck-hosted URL provided above. State fees are updated on a regular basis and linking to a TeleCheck-hosted page will minimize the number of maintenance updates required. The merchant may choose how you want to display the state fees. Suggestions include a new pop-up window, a full browser window, or directly on the checkout page.

NOTE

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

Prearranged Payments and Deposits Authorizations (PPD)

Payments are facilitated, not authorized.

Authorization is via paper from consumer to merchant.

PPD Authorization Requirements:







Must be face-to-face, in writing and signed.

Must clearly and conspicuously state it terms, such as consumer name, payment amount, payment timing (if recurring) and bank routing/account information. Must also provide that authorization may be revoked in the manner specified in the authorization.

Customer must be provided a copy.

Language Sample for PPD

By providing a check as payment, I authorize you to use information from my check to make a one-time electronic funds transfer (EFT) or draft from my account, or to process the payment as a check transaction. When you use information from my check to make an EFT, funds may be withdrawn from my account as soon as the same day my payment is received, and I will not receive my check back from my financial institution. The account referenced above is a

(check one):

Consumer account

Business account

If my payment is returned unpaid, I authorize you or your service provider to collect my payment and my state’s return fee set forth below by EFT(s) or draft(s) from my account. I understand that I can revoke this authorization by sending written notice to _____ in such time and manner as to afford ____ a reasonable opportunity to act on it. If this payment is from a corporate owned account, I make these authorizations as an authorized corporate representative and agree that the entity will be bound by the NACHA Operating Rules.

Returned Check Fees:

TeleCheck has posted a table of current state returned check fees at http://www.firstdata.com/support/telecheck_returned_check/returned_check_fees.htm. The


B


TeleCheck Authorization Requirements merchant should link directly to the TeleCheck-hosted URL provided above. State fees are updated on a regular basis and linking to a TeleCheck-hosted page will minimize the number of maintenance updates required. The merchant may choose how to display the state fees.

Suggestions include a new pop-up window, a full browser window, or directly on the checkout page.

AK

$30-

HI

$30-

MN

$30_œ

OH

$30^^

VI

$20

MO

$25

OK

$25

AL

$30

IA

$30

VT

$25‡

MS

$40

OR

$25

AR

$25

ID

$20-

WA

$30_◊

MT

$30

PA

$30

AZ

$25

IL

$25-

WI

$25-

NC

$25

PR

$10

CA

$25

IN

$20-

WV

$25

ND

$30

RI

$25

CO

$20-

KS

$30

WY

$30

NE

$35

SC

$30

CT

$20-

KY

$50

NH

$25

SD

$40

DE

$40

LA

$25^

DC

$25

MA

$25

NJ

$30

TN

$30-

FL

$25_ƒ

MD

$35

NM

$30

TX

$30†~

GA

$30^

ME

$25

NV

$25

UT

$20-

GU

$20

MI

$25

NY

$20-

VA

$50

Authorization – Sales Decline/Error

Authorization requests can fail for a number of reasons, ranging from missing or invalid fields to business decisions based on risk assessment. These different scenarios need to be handled differently by the merchant, and require different legal language to be displayed to the customer.

Sale Decline Required Language

We are sorry that we cannot accept your check at this time. Our decision is based, in whole or in part, on information provided to us by TeleCheck. We encourage you to call TeleCheck at 1-

800.366.2425 or write TeleCheck Customer Care at P.O. Box 4513, Houston, TX 77210-4513.

Please provide TeleCheck your driver's license number and the state where it was issued, and the complete banking numbers printed on the bottom of your check. Under the Fair Credit

Reporting Act, you have the right to a free copy of your information held in TeleCheck's files within 60 days from today. You may also dispute the accuracy or completeness of any information in TeleCheck's consumer report. TeleCheck did not make the adverse decision to not accept your payment item and is unable to explain why this decision was made.

Sale Error Responses

We are unable to process this transaction with the payment information provided. Please use a different form of payment at this time.


C

Submitting Purchasing Card

Level 2 and Level 3 Transactions

PayPal Payment Services supports passing Purchasing Card Level 2 information (such as purchase order number, tax amount, and charge description) in the settlement file.

If additional required invoice information and line-item details are included in the transaction,

PayPal formats Purchasing Card Level 3 information in an appropriate format, for example,

EDI (Electronic Data Interchange) 810 format as required by American Express during settlement processing.

Please contact your merchant bank to determine which parameters are required to obtain the best rate for level 2 or level 3 type transactions. If in doubt, we recommend you send all the level 2 and level 3 fields specified below for your processor.

About Purchasing Cards

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



Eliminate paper-based order systems and associated costs





Improve control and accountability through itemized statements

Foster better risk controls through spending limits and buying from approved vendors





Reduce administrative overhead by empowering employees to make small purchases

Enable enterprises to negotiate better contract pricing and discounts with suppliers by using vendor detail reports

To promote acceptance and usage of purchasing card programs, card issuers have established incentive rates for merchants. The incentive rates are available to merchants who comply at transaction processing Level 2 or Level 3. Transactions that comply at transaction processing

Level 1 qualify as normal credit card transactions.

NOTE

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

About Program Levels

The term Level does not apply to the card, but to the transaction data submitted for that card.

Generally, a higher level means more detailed data for reporting.

The following table describes the recognized transaction levels.


C

Submitting Purchasing Card Level 2 and Level 3 Transactions

About American Express Purchasing Card Transactions

Level

Level 1

Level 2

Level 3

Description

Function as normal credit cards and are authorized and associated with normal transaction data in authorization and settlement. Any merchant who accepts credit cards supports this level..

Additional data regarding sales tax, customer code, purchase order number, invoice number are captured at the point of sale. In most cases, this information is combined with the merchant’s tax ID number, state, and postal code data and is then passed through during settlement. For some processors and banks, however, a Level 2 authorization may include some of this data.

Significant additional information such as line items, product codes, item descriptions, unit price, unit quantities, and ship-to postal data are added to the Level

2 data to provide optimal reporting to buyers and sellers. Settlement transactions typically carry Level 3 data.

Level 2 and Level 3 data is generally considered non-financial data. Lack of adequate data may cause a transaction to be downgraded.

PayPal generally requires up to Level 2 information in an authorization transaction followed by additional Level 3 data in the associated delayed capture transaction. A sale transaction should include all Level 3 data since it is authorized and later settled.

Accepted BIN Ranges

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

About American Express Purchasing Card Transactions

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

Paymentech or First Data Nashville.

Supported Transaction Types

You can submit Level 3 parameters with delayed capture, sale, credit, or force transactions.

Level 3 data in authorization transactions is ignored. The Gateway decides whether a transaction meets Level 3 requirements during authorization.

Level 3 data is passed to the American Express processor only during settlement.



About American Express Purchasing Card Transactions

C

Avoiding Downgrade

If a transaction uses the purchasing card BIN range (see

“Accepted BIN Ranges” on page 146 )

and contains a line item but does not include all mandatory Level 3 parameters, the transaction succeeds but is processed as Level 2 or Level 1 during settlement (depending on which data was passed).

For downgraded transactions, with the VERBOSITY parameter set to HIGH, the ADDLMSGS field returns a message like the following:

Features not processed: PCARD L3 (missing or invalid: InvoiceNumber

RequestorName)

— or —

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

For details on VERBOSITY, see “VERBOSITY: Viewing Processor-Specific Transaction

Results” on page 199

Submitting Successful Level 3 Transactions

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

Edit Check

The Gateway performs an edit check on the transaction’s amount fields to ensure that all line item and tax amounts balance.

If the edit check fails, the transaction fails with Result 4: Invalid Amount.

To pass the edit check, the following relationship must be true:

Transaction Amount = Total Tax Amount + Total Freight Amount + Total

Handling Amount + Total Line Item Amount.

Transaction Amount

Total Tax Amount

Total Freight Amount

Total Handling Amount

Total Line Item Amount

Total amount for the transaction, AMT

TAXAMT

FREIGHTAMT

, or, if not present, the summation of L_FREIGHTAMT n for all line items

HANDLINGAMT

, or, if not present, the summation of L_HANDLINGAMT n for all line items

Summation of L_QTY n

* L_COST n for all line items ( n as the line item number). For example, if there are 2 line items, then the Total Line Item Amount would be (LQTY1*LCOST1) + (LQTY2*LCOST2)


C


American Express Purchasing Card Transaction Processing

Accepted BIN Ranges

The following BIN ranges are accepted for American Express Level 2 and Level 3 transactions:

37326

37429

37857

37859

37873

37965

146

American Express Purchasing Card Transaction Processing

The American Express supports Level 2 transaction data.

NOTE

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

Express Representative.

American Express Level 2 Parameters for American Express

The parameters to meet American Express reporting and statement requirements are described in the following tables.

CPC Level 2 Transaction Advice Addendum Parameters

Field

PONUM

SHIPTOZIP

TAXAMT

L_DESC1

Description

(Required) Purchase order number.


(Optional) Ship-to postal code (called zip code in the USA). This field must contain one of the following values:



Zip code of the destination where the merchandise is to be shipped



(If the above is not available) Zip code of the location where the merchant executed the transaction


(Optional) Total tax amount. Must include a decimal and the exact amount to the cent

(42.00, not 42). Do not include comma separators (1234.56 not 1,234.56).


(Optional) Description of this line item; if not provided, DESC1 (if present) is used.





C

Field

L_AMT1

L_QTY1

L_DESC2

L_AMT2

L_QTY2

L_DESC3

L_AMT3

L_QTY3

L_DESC4

L_AMT4

L_QTY4

Description

(Optional) Charge for this line item. Must include a decimal and be exact to the cent

(42.00, not 42) and exclude comma separators (1234.56 not 1,234.56).


(Optional) Quantity of this line item.























Field


MERCHANTNAME

MERCHANTSTREET

Description






C



Field

MERCHANTCITY

MERCHANTSTATE

MERCHANTZIP

Description

















CA

= California, USA

NS


COS

= Colima Mexico






MERCHANTCOUNTRYCODE



MERCHANTLOCATIONID



MERCHANTID



MERCHANTCONTACTINFO


NOTE






C

Field

ADDLAMT n


ADDLAMTTYPE n

Description






Example American Express Level 2 Transaction Parameter String

TRXTYPE=S&ACCT=372449635311003&AMT=20.06&BILLTOCITY=Mountain View&DESC1=des c1&DESC2=desc2&DESC3=desc3&DESC4=FRT10.00&EXPDATE=1215&BILLTOFIRSTNAME=Card holder first name&BILLTOLASTNAME=Cardholder last name&PARTNER=PayPal&PONUM=

12345&PWD=pwd&SHIPTOZIP=94045&BILLTOSTATE=CA&BILLTOSTREET=123 Main St.&TEND

ER=C&USER=user&BILLTOZIP=123451234

American Express Level 3 Parameters

American Express supports Level 3 transaction data. PayPal provides the Merchant

Registration data values: Supplier Name, Supplier City, Supplier State, Supplier Postal code,

Merchant No, and Federal Tax ID. The merchant provides the values listed in the the following table.

American Express Level 3 Parameters

Field

INVNUM

AUTHCODE

REQNAME

PONUM

Description


Character length and limitations: 1 to 9 alphanumeric characters

(Required) Authorization code. It is passed transparently for delayed capture. Use only with voice authorized force capture transactions.

(Required) Requester name.


(Required) Cardmember reference number.



C



Field

SHIPTOZIP

INVOICEDATE

AMT

TAXAMT

DESC

FREIGHTAMT

HANDLINGAMT

L_QTY n

L_UOM n

L_COST n

L_DESC n

L_CATALOGNUM n

L_COSTCENTERNUM n

Description

(Required) Ship-to postal code (called zip code in the USA). This field must contain one of the following values:



Zip code of the destination where the merchandise is to be shipped



(If the above is not available) Zip code of the location where the merchant executed the transaction


(Optional) Invoice date. Defaults to transaction date if not present.

Character length and limitations: 8 alphanumeric characters, in the YYYYMMDD format

(Required) Total transaction amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not

1,234.56

).

NOTE

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


(Required) Total tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not

1,234.56

).

Character length and limitations: 1 to 6 numeric characters

(Optional) Charge description. Defaults to “NO.”


(Optional) Total freight amount.


(Optional) Total handling amount.


Payflow SDK:

XMLPay: Item.Quantity

(Required) Quantity invoiced.


(Required) Unit of measure.


(Required) Unit price.


(Required) Description of the item.


(Required) Supplier’s catalog number.


(Required) Cost center number





C

Field

L_PRODCODE n

L_UPC n

L_TAXAMT n

L_FREIGHTAMT n

L_HANDLINGAMT n

L_TRACKINGNUM n

L_PICKUPSTREET n

L_PICKUPCITY n

L_PICKUPSTATE n

L_PICKUPZIP n

L_PICKUPCOUNTRY n

L_UNSPSCCODE n

Description

(Optional) The item’s supplier stock keeping unit (SKU) number.


(Optional) The item’s universal product code (UPC).


(Optional) Item tax amount.


(Optional) Freight amount.


(Optional)Handling amount.


(Optional) Tracking number.


(Optional) Drop-off address1.


(Optional) Drop-off city.


(Optional) Drop-off state.


(Optional) Drop-off postal or zip code.


(Optional) Drop-off country.


(Optional) UNSPSC code.


Example American Express Level 3 Transaction Parameter String

TRXTYPE=S&TENDER=C&partner=partner&PWD=test&USER=test&ACCT=378734493671000&

EXPDATE=1213&AMT=5.00&COMMENT1=PCARD Test&COMMENT2=Testing&BILLTOZIP=940151

234&BILLTOSTREET=123 Lincoln WAY&CVV2=0123&SHIPTOCOUNTRY=USA&CUSTCODE=12345

&FREIGHTAMT=1.00&ORDERDATE=021700&HANDLINGAMT=1.00&PONUM=123456789012345678

9012345&SHIPFROMZIP=940151234&SHIPTOZIP=940151234&TAXAMT=1.00&TAXEXEMPT=N&L

_UPC1=PN&L_QTY1=1&L_DESC1=Test123&L_UOM1=12&L_COST1=1.00&L_PRODCODE1=123&L_

COSTCENTERNUM1=55&L_TAXAMT1=0&L_QTY2=1&L_UPC1=PN&L_DESC2=Test&L_UOM2=12&L_C

OST2=1.00&L_PRODCODE2=1234&L_COSTCENTERNUM2=55&L_TAXAMT2=1.00&REQNAME=Rober t&SHIPTOZIP=543210&INVNUM=123456789&VERBOSITY=HIGH


C


Elavon (Formerly Nova) Purchasing Card Transaction Processing

Elavon (Formerly Nova) Purchasing Card Transaction

Processing

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

Elavon Level 2 Parameters

To get the discount rate, include both Level 2 parameters listed in the following table. Pass these parameters in authorization and sale transactions.

Level 2 Parameters

CUSTCODE

TAXAMT

Description

(Required) Customer code.


(Required) Sales tax.

The value must include a decimal and the exact amount to the cent (42.00, not 42).

Do not include comma separators (1234.56 not 1,234.56). To qualify for Level 2 discounts, this value must not be all zeros or blank spaces.


Elavon Additional Parameters

The following parameters are recommended to obtain the best rates for purchasing card transactions with Elavon:

Field

COMMCARD

PONUM

TAXAMT

Description

(Optional) Type of purchasing card account number sent. Is one of the following values:





P

= Purchase Card

C

= Corporate Card







B

= Business Card

U

= Unknown (default)

N

= None

Character length and limitations: 1 alphanumeric character, defaults to U


Character length and limitations: 25 alphanumeric characters, when used provides best rate

(Optional)Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56).

Character length and limitations: 10 currency characters, when used provides best rate



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

C

Example Elavon Level 2 Transaction Parameter String

TRXTYPE=S&ACCT=5105105105105100&AMT=20.10&BILLTOCITY=Mountain View&COMMENT1

=L2 Testing&EXPDATE=1215&BILLTOFIRSTNAME=Cardholder First Name&BILLTOLASTNA

ME=Cardholder Last Name&PARTNER=PayPal&PWD=pwd&BILLTOSTATE=CA&BILLTOSTREET=

123 Main St.&TENDER=C&USER=user&BILLTOZIP=94043&CUSTCODE=123456&TAXAMT=1.34

First Data Merchant Services (FDMS) Nashville Purchasing Card

Transaction Processing

NOTE

: FDMS Nashville supports Level 2 transaction processing only.

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

FDMS Nashville Commercial Card Parameters

Field

COMMCARD

DUTYAMT

FREIGHTAMT

PONUM

SHIPTOZIP

Description

(Optional) Type of purchasing card account number sent. Is one of the following values:

 P

= Purchase Card









C

= Corporate Card

B

= Business Card

U

= Unknown (default)

N

= None

Character length and limitations: 1 alphanumeric character, defaults to U

(Optional) Sometimes called import tax. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators

(1234.56 not 1,234.56).

Character length and limitations: 10 currency characters

(Optional) Freight amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not

1,234.56

).



Character length and limitations: 25 alphanumeric characters, provides best rate when used

(Optional)Ship to postal code (called zip code in the USA).

Character length and limitations: 9 numeric characters, provides best rate when used


C


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

Field

TAXAMT

TAXEXEMPT

Description

(Optional)Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56).

Character length and limitations: 10 currency characters, provides best rate when used

(Optional) Is the customer tax exempt?

Character length and limitations: 1 alphanumeric character, Y or N

First Data Merchant Services (FDMS) North Purchasing Card


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

FDMS North Purchasing Parameters

Field

SHIPTOCOUNTRY

DISCOUNT

DUTYAMT

FREIGHTAMT

PONUM

SHIPFROMZIP

SHIPTOZIP

TAXAMT

Description

(Optional) Destination country code. Visa and MasterCard are different.

Character length and limitations: 3 alpha characters

(Optional) Discount amount on total sale


(Optional) Sometimes called import tax. If the currency uses a decimal, then the value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56).



(Optional) Purchase order number / merchant-related data.


(Optional) The postal code (called zip code in the USA) from which shipping occurs.


(Optional) Ship to postal code (called zip code in the USA).


(Optional) Tax amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56).




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

C

FDMS North Purchasing Card Line Item Parameters

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

SHIPFROMZIP

parameter is required for Level 3 transactions.

FDMS North Line Item Parameters

Field

L_QTY n

L_COMMCODE n

L_DESC n

L_UOM n

L_COST n

L_UPC n

L_DISCOUNT n

L_AMT n

L_TAXAMT n

Description

(Required) Quantity (whole units only).


(Optional) Item commodity code.


(Optional) Item description.


(Optional) Item unit of measure.


(Optional) Cost per item, excluding tax.


(Optional) Supplier specific product code.


(Optional) Discount per line item.


(Optional) Total line item amount including tax and discount. + for debit, - for credits.


(Optional) Line item tax amount.


First Data Merchant Services South (FDMS) Purchasing Card


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


C



FDMS South Level 2 and Level 3 Purchasing Card Parameters

Field

BILLTOCITY

SHIPTOCOUNTRY

CUSTCODE

DISCOUNT

DUTYAMT

BILLTOFIRSTNAME

FREIGHTAMT

INVNUM

BILLTOLASTNAME

ORDERDATE

Description

(Optional) Cardholder’s city.


(Optional) Destination Country Code. Visa and MasterCard are different. Refer to

Country Code tables.


(Optional) Customer code/customer reference ID.


Discount amount on total sale.


(Optional) Sometimes called import tax. If the currency uses a decimal, then the value must include a decimal and the exact amount to the cent(42.00, not 42). Do not include comma separators (1234.56 not 1,234.56).


(Optional) Cardholder’s first name.


(Optional) Freight amount. If the currency uses a decimal, then the value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56).


(Optional) Merchant invoice number. This reference number (PNREF—generated by

PayPal) is used for authorizations and settlements.

The acquirer decides if this information will appear on the merchant’s bank reconciliation statement.


(Optional) Cardholder’s last name.


(Optional) Order date. Format is mmddyy with no slashes or dashes. For example,

July 28, 2003 is 072803.





C

Field

ORDERTIME

PONUM

SHIPFROMZIP

SHIPTOZIP

BILLTOSTATE

TAXAMT

TAXEXEMPT

Description

(Optional) Order time and date. Format is either YYYY-MM-DD or YYYY-MM-DD

HH:MI:SS

(where HH is in 24-hour time).

If the value does not conform to one of the formats or if the date is not valid (for example, 2004-17-35), then the transaction is rejected with a RESULT=7

(SIG_FIELD_ERR) and RESPMSG=Invalid ORDERTIME.

A truncated version of the ORDERTIME value (up to 7 characters) overwrites any value provided by ORDERDATE.

If no value is provided, a NULL value is stored.








(Optional) Cardholder’s state.



Character length and limitations: 10 currency characters, provides best rate when used

(Optional) Is the customer tax exempt?


FDMS South Line Item Parameters

Line item data (Level 3) describes the details of the item purchased and can be can be passed for each transaction. The convention for passing line item data in name-value pairs is that each name-value starts with L_ and ends with n where n is the line item number. For example

L_QTY0=1

is the quantity for line item 0 and is equal to 1, with n starting at 0.

FDMS South Purchasing Card Line Item Parameters

Field

L_QTY n

L_COMMCODE n

Description






C



Field

L_DESC n

L_UOM n

L_COST n

L_PRODCODE n

L_DISCOUNT n

L_AMT n

L_TAXAMT n

Description







(Optional) Supplier-specific product code.




(Required) Total line item amount including tax and discount. + for debit, - for credits.




Example FDMS South Purchasing Card Level 2 and 3 Parameter String

TRXTYPE=S&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant&P

WD=x1y2z3&BILLTOSTATE=CA&BILLTOFIRSTNAME=John&BILLTOLASTNAME=Smith&BILLTOCI

TY=Redwood&SHIPTOCOUNTRY=USA&CUSTCODE=12345&DISCOUNT=.25&DUTYAMT=34.00&FREI

GHTAMT=12.00&INVNUM=123456789&ORDERDATE=021700&PONUM=1234567890123456789012

345&SHIPFROMZIP=940151234&SHIPTOZIP=94065&TAXAMT=1.00&TAXEXEMPT=Y

Example FDMS South Line Item Parameter String

TRXTYPE=S&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant&P

WD=x1y2z3&BILLTOSTATE=CA&BILLTOFIRSTNAME=John&BILLTOLASTNAME=Smith&BILLTOCI

TY=Redwood&SHIPTOCOUNTRY=USA&CUSTCODE=12345&DISCOUNT=.25&DUTYAMT=34.00&FREI

GHTAMT=12.00&INVNUM=123456789&ORDERDATE=021700&PONUM=1234567890123456789012

345&SHIPFROMZIP=940151234&SHIPTOZIP=94065&TAXAMT=1.00&TAXEXEMPT=Y&L_QTY1=1&

L_UPC1=PN&L_DESC1=Test&L_UOM1=INQ&L_COST1=1.00&L_PRODCODE1=12345&L_DISCOUNT

1=.25&&L_AMT1=.75&L_TAXAMT1=0



Global Payments - Central Purchasing Card Transaction Processing

C

Global Payments - Central Purchasing Card Transaction

Processing

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

Global Payments - Central Level 2 Parameters

Pass the following Level 2 parameters to get the discount rate.

Global Payments - Central Level 2 parameters


CUSTCODE

TAXAMT

Description







Example Global Payments - Central Level 2 Visa or MasterCard Transaction

Parameter String


=L2 Testing&EXPDATE=1209&BILLTOFIRSTNAME=Cardholder First Name&BILLTOLASTNA

ME=Cardholder Last Name&PARTNER=PayPal&PWD=pwd&BILLTOSTATE=CA&BILLTOSTREET=


Global Payments - East Purchasing Card Transaction

Processing

Global Payments - East (NDCE) supports Level 2 parameters for American Express,

MasterCard, and Visa.

Global Payments - East Level 2 Parameters

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


C


Heartland Purchasing Card Transaction Processing


CUSTCODE

TAXAMT

Description







Example Global Payments - East Level 2 Visa or MasterCard Transaction



=L2 Testing&EXPDATE=1215&BILLTOFIRSTNAME=Cardholder FirstName&BILLTOLASTNAM

E=Cardholder LastName&PARTNER=PayPal&PWD=pwd&BILLTOSTATE=CA&BILLTOSTREET=12


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

Heartland Purchasing Card Transaction Processing

Heartland Level 2 Parameters

Heartland supports MasterCard and Visa for Level 2 processing.

Heartland indicates in the authorization response whether the credit card in the transaction is a commercial card. Based on the commercial card indicator, Payflow will format the Level 2 information in the settlement request.

Heartland Level 2 Transaction Data

To get the discount rate, pass the Level 2 values marked Required in the following table.

Parameter

PONUM

Description

(Required) Customer reference ID.





C

Parameter

TAXAMT

TAXEXEMPT

Description

(Required) Tax amount.




(Optional) Tax amount identifier.

Character length and limitations: 1 alpha character, Y or N

Example Heartland Level 2 Visa Transaction Parameter String


=L2 Testing&EXPDATE=1215&INVNUM=661254585&BILLTOFIRSTNAME=CardHolder Name&P

ARTNER=PayPal&PWD=pwd&BILLTOSTATE=CA&BILLTOSTREET=123 Main St.&TAXAMT=1.01&

TAXEXEMPT=N&TENDER=C&USER=user&BILLTOZIP=94043

Heartland Level 3 MasterCard Parameters

To qualify for Level 3, the authorization response for the transaction must have the commercial card indicator set and one or more line items should be present in the delayed capture or sale request.

Level 2 transaction parameters marked as Required are required for Level 3 transactions.

Level 3 transactions that do not include the required Level 2 values are rejected.

IMPORTANT

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

Heartland Level 2 MasterCard Parameters Required for Level 3 Transactions

Parameter

PONUM

TAXAMT

LOCALTAXAMT

TAXEXEMPT

Description

(Required) Purchase identifier.






(Optional) Local tax.


(Optional) Local tax incl flag.

Character length and limitations: 1 alphanumeric, Y or N


C



Parameter

NATIONALTAXAMT

INVNUM

Description

(Optional) National tax amount. You may omit this parameter if there is no such tax.


(Required) Purchase Order number or customer reference ID. The PNREF value is sent if no value is provided.


Heartland Level 3 MasterCard Extended Data

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


FREIGHTAMT



DUTYAMT

SHIPTOZIP

SHIPFROMZIP

SHIPTOCOUNTRY

ALTTAXAMT

(Optional) Duty amount.


(Required) The zip code of the address to which the goods are shipped.


(Required) The postal code (called zip code in the USA) from which shipping occurs.


(Optional) Destination country code.


(Optional) Alternate tax amount.


Heartland Level 3 MasterCard Line Item Detail Records

NOTE

: For these values, n is a sequence counter that should begin with 1 and increase in sequence. Each line item should also contain quantity (L_QTY n ) and unit price

(L_COST n ) fields.


L_COMMCODE n (Optional) Item commodity code.


L_DESC n (Required) Item descriptor.


L_UPC n (Optional) Product code.





C


L_QTY n (Required) Quantity.


L_UOM n (Required) Unit of measure code.


L_COST n

L_TAXAMT n

(Required) Unit cost.


(Optional) VAT/tax amount.


L_TAXRATE n

L_DISCOUNT n

(Optional) VAT/tax rate.




L_AMT n (Optional) Line-item total.


Example Heartland Level 3 MasterCard Transaction Parameter String.

TRXTYPE=S&TENDER=C&PARTNER=Partner&USER=User&PWD=Password&ACCT=552500000000

0005&EXPDATE=1215&AMT=1.00&BILLTOSTREET=5199 JOHNSON&BILLTOZIP=94588&ALTTAX

AMT=1.00&CUSTVATREGNUM=11111&LOCALTAXAMT=1.00&NATIONALTAXAMT=1.00&COMMCODE=

22222&VATAXAMT=1.00&VATAXPERCENT=10&TAXEXEMPT=Y&DISCOUNT=1.00&FREIGHTAMT=1.

00&DUTYAMT=1.00&SHIPTOZIP=33333&SHIPFROMZIP=44444&SHIPTOCOUNTRY=840&ORDERDA

TE=020725&L_COMMCODE1=123456789ABC&L_DESC1=Line item 1 description&L_UPC1=C

BA987654321&L_QTY1=1&L_UOM1=123456789012&L_COST1=1.00&L_TAXAMT1=1.00&L_TAXR

ATE1=1.00&L_DISCOUNT1=1.00&L_AMT1=1.00&L_TAXTYPE1=TT3

Heartland Level 3 Visa Parameters

To qualify for Level 3 transactions, the authorization response for the transaction must have the commercial card indicator set and one or more line items should be present in the delayed capture or sale request.



IMPORTANT


Heartland Level 2 Visa Parameters Required for Level 3 Transactions

Parameter

PONUM

Description

(Required) Purchase identifier. TheTransaction ID is sent if no value is provided.



C



Parameter

TAXAMT

LOCALTAXAMT

TAXEXEMPT

NATIONALTAXAMT

INVNUM

Description



Do not include comma separators (1234.56 not 1,234.56).


(Optional) Local tax amount.


(Optional) Local tax incl flag.


(Optional) National tax amount.


(Required) Purchase order number/customer reference ID. The Transaction ID is sent if no value is provided.


Heartland Level 3 Visa Extended Data



COMMCODE

DISCOUNT

(Optional) Summary commodity code identifier for the business.


(Optional) Discount amount.


FREIGHTAMT

DUTYAMT

ORDERDATE

SHIPTOZIP

SHIPFROMZIP

SHIPTOCOUNTRY



(Optional)Duty amount.


(Required) Order date. Format is mmddyy with no slashes or dashes. For example,

July 28, 2003 is 072803.











C


VATREGNUM

FREIGHTAMT

(Required) VAT registration number. Can be part of the registration data or passed with each transaction.


(Required) Unique VAT inventory reference number. Can be part of the registration data or passed with each transaction.


CUSTVATREGNUM

VATTAXAMT

VATTAXPERCENT

(Required) Customer VAT registration number.


(Optional) VAT/tax amount (freight/shipping).


(Optional) VAT/tax rate (freight/shipping).


Heartland Level 3 Visa Line Item Detail Records




L_DESC n

L_UPC n

(Required) Item descriptor.


(Optional) Product code.


L_QTY n

L_UOM n

(Required) Quantity.


(Required) Unit of measure code.


L_COST n

L_TAXAMT n





L_TAXRATE n

L_DISCOUNT n








C


Litle Purchasing Card Transaction Processing

Example Heartland Level 3 Visa Transaction Parameter String


1111&EXPDATE=1215&AMT=1.00&BILLTOSTREET=5199 JOHNSON&TAXAMT=1.06&BILLTOZIP=

94588&ALTTAXAMT=1.00&CUSTVATREGNUM=11111&LOCALTAXAMT=1.01&NATIONALTAXAMT=1.

02&COMMCODE=22222&VATAXAMT=1.03&VATAXPERCENT=55&TAXEXEMPT=N&DISCOUNT=.50&FR

EIGHTAMT=1.00&DUTYAMT=1.00&SHIPTOZIP=33333&SHIPFROMZIP=44444&SHIPTOCOUNTRY=

840&ORDERDATE=020725&L_COMMCODE1=123456789ABC&L_DESC1=Line item 1 descripti on&L_UPC1=CBA987654321&L_QTY1=1&L_UOM1=123456789012&L_COST1=1.50&L_TAXAMT1=

1.05&L_TAXRATE1=12&L_DISCOUNT1=.50&L_AMT1=1.00&L_TAXTYPE1=TT1

Litle Purchasing Card Transaction Processing

Litle Level 2 Parameters

The Litle platform supports Level 2 transaction data.


Field

CUSTREF

DISCOUNT

DUTYAMT

FREIGHTAMT

TAXAMT

L_AMT n

Description

(Optional) Reference, such as a purchase order number, used by the customer for the purchase.


(Optional) Discount amount for the order.

Character length and limitations: The decimal is implied. If, for example, you specify

500, this value is equivalent to $5.00. 8 numeric characters

(Optional) Duty amount on the total purchased for the order.



(Optional) Shipping amount for the order.



(Optional) Tax amount included in the amount of the transaction.



(Optional) Amount of this line-item including tax, where n is a line-item number from 1 to 99. L_AMT n - L_TAXAMT n = line-item total.





Litle Purchasing Card Transaction Processing

C

Field

L_COMMCODE n

L_COST n

L_DESC n

L_DISCOUNT n

L_PRODCODE n

L_QTY n

L_TAXAMT n

L_UOM n

Description

(Optional) Identifier assigned by the card acceptor that categorizes the purchased item, where n is a line-item number from 1 to 99.


(Required if L_QTY n is supplied) Price of one unit of the item purchased, where n is a line-item number from 1 to 99.


(Required) Description of this line-item, where n is a line-item number from 1 to 99.


(Optional) Discount per line item, where n is a line-item number from 1 to 99.



(Optional) Supplier-specific product code of the purchased item, where n is a lineitem number from 1 to 99.


(Optional) Number of items purchased, where n is a line-item number from 1 to 99.


(Optional) Line item tax amount, where n is a line-item number from 1 to 99.

L_AMT n - L_TAXAMT n = line-item total.

Characteristic length and limitations: The decimal is implied. If, for example, you specify 500, this value is equivalent to $5.00. 8 numeric characters

(Optional) Unit of measure of the purchased item (such as kit, pair, gallon or month), where n is a line-item number from 1 to 99.



The Litle platform supports Level 3 transaction data.


Field

CUSTREF

DISCOUNT

DUTYAMT

Description

(Optional) Reference, such as a purchase order number, used by the customer for the purchase.


(Optional) Discount amount for the order.



(Optional) Duty amount on the total purchased for the order.




C


Merchant e-Solutions Purchasing Card Transaction Processing

Field

FREIGHTAMT

TAXAMT

L_AMT n

L_COMMCODE n

L_COST n

L_DESC n

L_DISCOUNT n

L_PRODCODE n

L_QTY n

L_TAXAMT n

L_UOM n

Description

(Optional) Shipping amount for the order.



(Optional) Tax amount included in the amount of the transaction.



(Optional) Amount of this line-item including tax, where n is a line-item number from 1 to 99. L_AMT n - L_TAXAMT n = line-item total.



(Optional) Identifier assigned by the card acceptor that categorizes the purchased item, where n is a line-item number from 1 to 99.


(Required if L_QTY n is supplied) Price of one unit of the item purchased, where n is a line-item number from 1 to 99.


(Required) Description of this line-item, where n is a line-item number from 1 to 99.


(Optional) Discount per line item, where n is a line-item number from 1 to 99.



(Optional) Supplier-specific product code of the purchased item, where n is a lineitem number from 1 to 99.


(Optional) Number of items purchased, where n is a line-item number from 1 to 99.


(Optional) Line item tax amount, where n is a line-item number from 1 to 99.

L_AMT n - L_TAXAMT n = line-item total.

Characteristic length and limitations: The decimal is implied. If, for example, you specify 500, this value is equivalent to $5.00. 8 numeric characters

(Optional) Unit of measure of the purchased item (such as kit, pair, gallon or month), where n is a line-item number from 1 to 99.


Merchant e-Solutions Purchasing Card Transaction Processing




C

Merchant e-Solutions Level 2 Parameters

Merchant e-Solutions supports MasterCard and Visa for Level 2 processing.

Merchant e-Solutions indicates in the authorization response whether the credit card in the transaction is a commercial card. Based on the commercial card indicator, Payflow will format the Level 2 information in the settlement request.

Merchant e-Solutions Level 2 Transaction Data

To get the discount rate, Level 2 values marked as Required in the following table must be present.

Parameter

PONUM

TAXAMT

TAXEXEMPT

Description









Example Merchant e-Solutions Level 2 Visa Transaction Parameter String


=L2 Testing&EXPDATE=1215&INVNUM=661254585&BILLTOFIRSTNAME=CardHolder Name&P

ARTNER=PayPal&PWD=pwd&BILLTOSTATE=CA&BILLTOSTREET=123 Main St.&TAXAMT=1.01&

TAXEXEMPT=N&TENDER=C&USER=user&BILLTOZIP=94043

Merchant e-Solutions Level 3 MasterCard Parameters

To qualify for Level 3, the authorization response for the transaction must have the commercial card indicator set and one or more line items should be present in the delayed capture or sale request.



IMPORTANT



C



Merchant e-Solutions Level 2 MasterCard Parameters Required for Level 3

Transactions

Parameter

PONUM

TAXAMT

LOCALTAXAMT

TAXEXEMPT

NATIONALTAXAMT

INVNUM

Description

(Required) Purchase identifier.










(Optional) National tax amount. You may omit this parameter if there is no such tax.


(Required) Purchase Order number or customer reference ID. The PNREF value is sent if no value is provided.


Merchant e-Solutions Level 3 MasterCard Extended Data



FREIGHTAMT

DUTYAMT





SHIPTOZIP

SHIPFROMZIP

SHIPTOCOUNTRY

ALTTAXAMT












C

Merchant e-Solutions Level 3 MasterCard Line Item Detail Records

NOTE

: For the following values, n is a sequence counter that should begin with 1 and increase in sequence. With each line item, include the quantity (L_QTY n ) and unit price

(L_COST n ) fields.






L_UPC n

L_QTY n





L_UOM n

L_COST n

(Required) Unit of measure code.




L_TAXAMT n

L_TAXRATE n





L_DISCOUNT n

L_AMT n



(Optional) Line-item total.


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










C



Merchant e-Solutions Level 3 Visa Parameters

To qualify for Level 3 transactions, the authorization response for the transaction must have the commercial card indicator set and one or more line items should be present in the delayed capture or sale request.



IMPORTANT


Merchant e-Solutions Level 2 Visa Parameters Required for Level 3

Transactions

Parameter

PONUM

TAXAMT

LOCALTAXAMT

TAXEXEMPT

NATIONALTAXAMT

INVNUM

Description

(Required) Purchase identifier. TheTransaction ID is sent if no value is provided.






(Optional) Local tax amount.


(Optional) Local tax incl flag.


(Optional) National tax amount.


(Required) Purchase order number/customer reference ID. The Transaction ID is sent if no value is provided.


Merchant e-Solutions Level 3 Visa Extended Data



COMMCODE



DISCOUNT






C


FREIGHTAMT

DUTYAMT



(Optional)Duty amount.


ORDERDATE

SHIPTOZIP

SHIPFROMZIP

SHIPTOCOUNTRY

(Required) Order date. Format is mmddyy with no slashes or dashes. For example,

July 28, 2003 is 072803.








VATREGNUM

FREIGHTAMT

CUSTVATREGNUM

VATTAXAMT

VATTAXPERCENT



(Required) Unique VAT inventory reference number. Can be part of the registration data or passed with each transaction.


(Required) Customer VAT registration number.






Merchant e-Solutions Level 3 Visa Line Item Detail Records




L_DESC n

L_UPC n








C


Paymentech Salem (New Hampshire) Purchasing Card Transaction Processing


L_UOM n (Required) Unit of measure code.


L_COST n (Required) Unit cost.


L_TAXAMT n

L_TAXRATE n





L_DISCOUNT n

L_AMT n





Example Merchant e-Solutions Level 3 Visa Transaction Parameter String








Paymentech Salem (New Hampshire) Purchasing Card


Paymentech Salem (New Hampshire) Level 2 Parameters for American

Express

The Paymentech Salem (New Hampshire) platform supports Level 2 parameters for American

Express, MasterCard, Visa, and Switch/Solo Maestro. The parameters in the following tables meet card acceptance and American Express reporting and statement requirements.




C

Field

PONUM

SHIPTOZIP

TAXAMT

L_DESC1

L_AMT1

L_QTY1

L_DESC2

L_AMT2

L_QTY2

L_DESC3

L_AMT3

L_QTY3

L_DESC4

L_AMT4

L_QTY4

CPC Level 2 Transaction Advice Addendum Parameters

Description

(Required) Purchase order number.


(Required) Ship-to postal code (called zip code in the USA).


(Optional) Total tax amount. Must include a decimal and be exact to the cent (42.00, not 42) and exclude comma separators (1234.56 not 1,234.56).


(Optional) Description of this line item; if not provided, DESC1 (if present) is used.


(Optional) Charge for this line item. Must include a decimal and be exact to the cent



(Optional) Quantity of this line item.


(Optional) Description of this line item; if not provided, DESC2 (if present) is used.





(Optional) Quantity of this line item


(Optional) Description of this line item; if not provided, DESC3 (if present) is used







(Optional) Description of this line item; if not provided, DESC4 (if present) is used








C




Field

MERCHANTNAME

MERCHANTSTREET

Description





MERCHANTCITY

MERCHANTSTATE

MERCHANTZIP

















CA

= California, USA

NS


COS

= Colima Mexico





Character length and limitations; 15 alphanumeric characters

MERCHANTCOUNTRYCODE



MERCHANTLOCATIONID


NOTE

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

Account Manager for details.





C

Field Description

MERCHANTID


NOTE




MERCHANTCONTACTINFO


NOTE





Field

ADDLAMT n

ADDLAMTTYPE n

Description






Paymentech Salem (New Hampshire) Level 3 Purchasing Card Parameters

Paymentech Salem (New Hampshire) supports Level 3 parameters for MasterCard and Visa.

Both Level 2 transaction parameters in the following table are required for Level 3 transactions. Level 3 transactions that do not include them are rejected.

Paymentech Salem (New Hampshire) Level 2 Parameters Required for Level 3

Transactions

To get the discount rate, pass both Level 2 parameters in the following table.

Level 2 Parameters Required for Level 3 Transactions

Parameter

PONUM

Description

(Required) Customer reference number.



C



Parameter

TAXAMT

Description





Paymentech Salem (New Hampshire) Level 3 MasterCard Parameters

Level 3 MasterCard Order Parameters


FREIGHTAMT

DUTYAMT

SHIPTOZIP

SHIPTOCOUNTRY

(Required) Freight amount.


(Required) Duty amount.


(Required) Destination zip code.

(Optional) Destination country.

SHIPFROMZIP

DISCOUNT

ALTERNATETAXID

ALTERNATETAXAMT

(Required) Ship from zip code.

(Required) Discount amount.


(Optional) Alternate tax ID.



. Level 3 MasterCard Line Item Record #1 Parameters


L_DESC n

L_PRODCODE n

(Required) Description.


L_QTY n

L_UOM n




TAXAMT n

L_TAXRATE n

(Optional) Tax amount.


(Optional) Tax rate.





C

. Level 3 MasterCard Line Item Record #2 Parameters




L_DISCOUNT n (Optional) Discount amount.


L_TAXTYPE n (Optional) Tax type applied.

Paymentech Salem (New Hampshire) Level 3 Visa Parameters

Level 3 Visa Order Parameters


FREIGHTAMT

DUTYAMT

SHIPTOZIP

SHIPTOCOUNTRY

(Required) Freight amount.


(Required) Duty amount.


(Required) Destination zip code.

(Optional) Destination country.

SHIPFROMZIP

DISCOUNT

TAXAMT

TAXPERCENTAGE

(Required) Ship from zip code.

(Required) Discount amount.


(Optional) VAT/Tax ID.


(Optional) VAT/Tax amount.

. Level 3 Visa Line Item Record #1 Parameters


L_DESC n

L_PRODCODE n

(Required) Description.

(Required) Product code.

L_QTY n

L_UOM n




TAXAMT n

L_TAXRATE n

(Optional) Tax amount.


(Optional) Tax rate.



C


Paymentech Tampa Level 2 Purchasing Card Transaction Processing

. Level 3 Visa Line Item Record #2 Parameters






L_UPC n

L_COST n


(Optional) Unit cost.


Example Paymentech Salem (New Hampshire) Level 3 MasterCard Transaction


TRXTYPE=S&TENDER=C&PARTNER=Partner&PWD=Password&USER=User&ACCT=548018000000

0024&EXPDATE=1215&AMT=1.00&COMMENT1=0508&BILLTOFIRSTNAME=Robert&BILLTOSTREE

T=123 Main St.&BILLTOZIP=94065&CVV2=426&PONUM=ABCDEFGHIJ&TAXAMT=1.00&FREIGH

TAMT=2.00&DUTYAMT=3.00&SHIPTOZIP=94543&SHIPTOCOUNTRY=840&SHIPFROMZIP=94509&

ALTERNATETAXID=10&ALTERNATETAXAMT=4.00&L_DESC1=MC Pcard&L_UPC1=1&L_QTY1=2&L

_UOM1=3&L_TAXAMT1=4&L_TAXRATE1=5&L_AMT1=6&L_DISCOUNT1=7&L_TAXTYPE1=8

Example Paymentech Salem (New Hampshire) Level 3 Visa Transaction


TRXTYPE=S&TENDER=C&PARTNER=Partner&PWD=Password&USER=User&ACCT=427533001234

5626&EXPDATE=1215&AMT=1.00&COMMENT1=0508&BILLTOFIRSTNAME=Robert&BILLTOSTREE

T=123 Main St.&BILLTOZIP=94065&CVV2=426&PONUM=ABCDEFGHIJ&TAXAMT=1.00&FREIGH

TAMT=2.00&DUTYAMT=3.00&SHIPTOZIP=94543&SHIPTOCOUNTRY=840&SHIPFROMZIP=94509&

DISCOUNT=4.00&VATAXAMT=5.00&VATAXPERCENT=10&L_DESC1=TSYS Acquiring Solution s Pcard&L_UPC1=1&L_UOM1=2&L_QTY1=3&L_TAXAMT1=4&L_TAXRATE1=5&L_AMT1=6&L_DISC

OUNT1=7&L_COMMCODE1=8&L_COST1=9&L_COST1=10

Paymentech Tampa Level 2 Purchasing Card Transaction

Processing

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



SecureNet Purchasing Card Transaction Processing

C

Paymentech Tampa Level 2 Parameters

Paymentech Tampa


PONUM

TAXAMT

TAXEXEMPT

SHIPTOZIP

Description

(Required) Customer reference number.






(Required) Tax exempt.


(Required) Ship-to postal code (called zip code in the USA).


Example Paymentech Tampa Level 2 Visa and MasterCard Transaction


TRXTYPE=S&TENDER=C&PWD=PWD&USER=USER&PARTNER=PARTNER&ACCT=4275330012345675&

EXPDATE=1215&AMT=12.59&VERBOSITY=HIGH&BILLTOSTREET=123 Main St.&BILLTOZIP=4

9801&CVV2=248&TAXAMT=1.22&PONUM=AB12345678&SHIPTOZIP=98765&TAXEXEMPT=N

SecureNet Purchasing Card Transaction Processing

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

SecureNet Level 2 Parameters

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

SecureNet indicates in the authorization response whether the credit card in the transaction is a commercial card. Based in the commercial card indicator, Payflow will format the Level 2 information in the settlement request.

To get the discount rate, Level 2 parameters marked as Required in the following table must be present .


C



SecureNet Level 2 Parameters

Parameter

PONUM

TAXAMT

TAXEXEMPT

Description









Example SecureNet Level 2 Visa Transaction Parameter String.


=L2 Testing&EXPDATE=1215&INVNUM=661254585&BILLTOFIRSTNAME=CardHolder First

Name&BILLTOLASTNAME=CardHolder Last Name&PARTNER=PayPal&PWD=pwd&BILLTOSTATE

=CA&BILLTOSTREET=123 Main St.&TAXAMT=1.01&TAXEXEMPT=N&TENDER=C&USER=user&BI

LLTOZIP=94043

SecureNet Level 3 MasterCard Parameters

To qualify for Level 3 purchasing card transaction processing, the authorization response for the transaction must have the commercial card indicator set and one or more line items should be present in the delayed capture or sale request.



IMPORTANT


SecureNet Level 2 MasterCard Parameters Required for Level 3 Line Item

Transactions

Parameter

PONUM

TAXAMT

LOCALTAXAMT

Description

(Required) Purchase identifier. The transaction ID is sent if no value is provided.


(Required)Tax amount.









C

Parameter

TAXEXEMPT

NATIONALTAXAMT

INVNUM

Description



(Optional)National tax amount.


(Required) Purchase order number/customer reference ID. The value of PNREF is sent if the INVNUM parameter is not provided.


SecureNet Level 3 MasterCard Extended Data



FREIGHTAMT

DUTYAMT





SHIPTOZIP

SHIPFROMZIP

SHIPTOCOUNTRY

ALTTAXAMT









SecureNet Level 3 MasterCard Line Item Detail Records

NOTE

: For these values, n is a sequence counter that should begin with 1 and increase in sequence. Each line item should also contain quantity (L_QTY <n> ) and unit price

(L_COST <n> ) fields.







C






L_UOM n (Required)Unit of measure/code.


L_TAXRATE n

L_TAXTYPE n

(Optional) Tax rate applied.


(Optional) Tax type applied.


L_TAXAMT n

L_DISCOUNT n

(Optional)Tax amount.




Example SecureNet Level 3 MasterCard Transaction Parameter String









SecureNet Acquiring Solutions Level 3 Visa Parameters




IMPORTANT


SecureNet Level 2 Visa Parameters for Level 3 Line Item Transactions

Parameter

PONUM

Description






C

Parameter

TAXAMT

LOCALTAXAMT

TAXEXEMPT

NATIONALTAXAMT

INVNUM

Description













SecureNet Level 3 Visa Extended Data

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

Parameter

COMMCODE

DISCOUNT

FREIGHTAMT

DUTYAMT

ORDERDATE

SHIPTOZIP

SHIPFROMZIP

SHIPTOCOUNTRY

Description

(Optional) Commodity code identifier for the business.








(Required) Order date. The format is mmddyy with no slashes or dashes. For example,

July 28, 2003 is 072803.









C



Parameter

VATREGNUM

FREIGHTAMT

CUSTVATREGNUM

VATTAXAMT

VATTAXPERCENT

Description



(Required) Unique VAT inv reference number. Can be part of the registration data or passed with each transaction.


(Required) Customer VAT Registration Number.


(Optional)VAT/tax amount (freight/shipping).




SecureNet Level 3 Visa Line Item Detail Records

NOTE


(L_COST n ) fields.




L_DESC n

L_UPC n





L_QTY n

L_UOM n

(Required) Item quantity.


(Required) Unit of measure/code.


L_COST n

L_TAXAMT n





L_TAXRATE n

L_DISCOUNT n







TSYS Acquiring Solutions Purchasing Card Transaction Processing

C




Example SecureNet Level 3 Visa Transaction Parameter String








TSYS Acquiring Solutions Purchasing Card Transaction

Processing

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

TSYS Acquiring Solutions Level 2 Parameters

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

TSYS Acquiring Solutions indicates in the authorization response whether the credit card in the transaction is a commercial card. Based in the commercial card indicator, Payflow will format the Level 2 information in the settlement request.

To get the discount rate, Level 2 parameters marked as required in the following table must be present .

TSYS Acquiring Solutions Level 2 Parameters

Parameter

PONUM

TAXAMT

Description








C



Parameter

TAXEXEMPT

Description



Example TSYS Acquiring Solutions Level 2 Visa Transaction Parameter String.


=L2 Testing&EXPDATE=1215&INVNUM=661254585&BILLTOFIRSTNAME=CardHolder First

Name&BILLTOLASTNAME=CardHolder Last Name&PARTNER=PayPal&PWD=pwd&BILLTOSTATE

=CA&BILLTOSTREET=123 Main St.&TAXAMT=1.01&TAXEXEMPT=N&TENDER=C&USER=user&BI

LLTOZIP=94043

TSYS Acquiring Solutions Level 3 MasterCard Parameters




IMPORTANT


TSYS Acquiring Solutions Level 2 MasterCard Parameters Required for Level 3

Line Item Transactions

Parameter

PONUM

TAXAMT

LOCALTAXAMT

TAXEXEMPT

NATIONALTAXAMT

INVNUM

Description


















C

TSYS Acquiring Solutions Level 3 MasterCard Extended Data



FREIGHTAMT



DUTYAMT

SHIPTOZIP

SHIPFROMZIP

SHIPTOCOUNTRY

ALTTAXAMT











TSYS Acquiring Solutions Level 3 MasterCard Line Item Detail Records

NOTE

: For these values, n is a sequence counter that should begin with 1 and increase in sequence. Each line item should also contain quantity (L_QTY <n> ) and unit price

(L_COST <n> ) fields.






L_QTY n

L_UOM n



(Required)Unit of measure/code.


L_TAXRATE n

L_TAXTYPE n

(Optional) Tax rate applied.




L_TAXAMT n (Optional)Tax amount.



C






Example TSYS Acquiring Solutions Level 3 MasterCard Transaction Parameter

String









TSYS Acquiring Solutions Level 3 Visa Parameters




IMPORTANT


TSYS Acquiring Solutions Level 2 Visa Parameters for Level 3 Line Item

Transactions

Parameter

PONUM

TAXAMT

LOCALTAXAMT

TAXEXEMPT

NATIONALTAXAMT

Description
















C

Parameter

INVNUM

Description



TSYS Acquiring Solutions Level 3 Visa Extended Data

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

Parameter

COMMCODE

DISCOUNT

FREIGHTAMT

DUTYAMT

ORDERDATE

SHIPTOZIP

SHIPFROMZIP

SHIPTOCOUNTRY

VATREGNUM

FREIGHTAMT

CUSTVATREGNUM

VATTAXAMT

VATTAXPERCENT

Description

(Optional) Commodity code identifier for the business.








(Required) Order date. The format is mmddyy with no slashes or dashes. For example,

July 28, 2003 is 072803.










(Required) Unique VAT inv reference number. Can be part of the registration data or passed with each transaction.


(Required) Customer VAT Registration Number.


(Optional)VAT/tax amount (freight/shipping).





C



TSYS Acquiring Solutions Level 3 Visa Line Item Detail Records

NOTE


(L_COST n ) fields.






L_UPC n

L_QTY n



(Required) Item quantity.


L_UOM n

L_COST n

(Required) Unit of measure/code.




L_TAXAMT n

L_TAXRATE n





L_DISCOUNT n

L_AMT n





Example TSYS Acquiring Solutions Level 3 Visa Transaction Parameter String










Vantiv Purchasing Card Transaction Processing

C

Vantiv Purchasing Card Transaction Processing

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

Vantiv Purchasing Parameters

Field

SHIPTOCOUNTRY

DISCOUNT

DUTYAMT

FREIGHTAMT

PONUM

SHIPFROMZIP

SHIPTOZIP

TAXAMT

Description

(Optional) Destination country code. Visa and MasterCard are different.


(Optional) Discount amount on total sale


(Optional) Sometimes called import tax. If the currency uses a decimal, then the value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not 1,234.56).











Vantiv Purchasing Card Line Item Parameters

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

SHIPFROMZIP

parameter is required for Level 3 transactions.


C


WorldPay Purchasing Cards Transaction Processing

Field

L_QTY n

L_COMMCODE

L_DESC

L_UOM

L_COST

L_UPC

L_AMT n n n n

L_TAXAMT n

Vantiv Line Item Parameters

L_DISCOUNT n n n

Description











(Optional) Supplier specific product code.




(Optional) Total line item amount including tax and discount. + for debit, - for credits.




WorldPay Purchasing Cards Transaction Processing

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

WorldPay Level 2 Parameters

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

WorldPay Level 2 parameters


ALTTAXAMT

COMMCODE

Description








C


COUNTRYCODE

CUSTDATA

CUSTOMERID

CUSTOMERNUMBER

DISCOUNT

DLNAME

DLNUM

DOB

DUTYAMT

FREIGHTAMT

INVNUM

MERCHANTDESCR

MERCHANTINVNUM

MERCHANTVATNUM

MERCHANTZIP

Description

(Optional) Country code.


(Optional) Generic data the merchant can pass to the WorldPay processor.




(Optional) Customer number.


(Optional) Discount amount on total sale.


(Optional) Account holder’s driver license name.

Character length and limitations: 95characters

(Optional) Account holder’s driver license number.


(Optional) Account holder’s date of birth in the format MMDDYYYY. For example, July

28, 2011 is represented as: 07282011


(Optional) Sometimes called import tax.

Character length and limitations: The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not

1,234.56). 10 currency characters

(Optional) Total freight amount.

Character length and limitations: The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56 not

1,234.56). 10 currency characters

(Optional) Merchant invoice number for the transaction.


(Optional) Description of product.


(Optional) Merchant invoice number.


(Optional) Merchant value added tax number.

Character length and limitations: 95 alphanumericcharacters

(Optional) 5- to 9-digit zip (postal) code excluding spaces, dashes, and nonnumeric characters where the transaction took place.




C




MISCDATA

ORDERDATE

PONUM

SHIPTOZIP

TAXAMT

TAXEXEMPT

VATINVNUM

VATNUM

VATTAXAMT

VATTAXRATE

Description

(Optional) Miscellaneous data.


(Required) Order date. The format is MMDDYY with no slashes or dashes. For example,

July 28, 2011 is 072811.






(Optional) Sales tax.




(Optional) Indicates whether the customer is tax exempt. It is one of the following values:





Y

– The customer is tax exempt.

N

– The customer is not tax exempt (default).

Character length and limitations: 1alpha character

(Optional) Value added tax invoice number.


(Optional) Customer valued added tax number.






WorldPay Level 3 Parameters

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

WorldPay Level 3 parameters


L_ALTTAXAMT n

Description

(Optional) Alternate tax amount for this item.

Character length and limitations: 8 numeric characters plus decimal: XXXX.XX




C


L_ALTTAXRATE

L_ALTTAXID

L_EXTAMT n

L_TAXTYPE

L_COMMCODE

L_DESC

L_AMT

L_SKU

L_QTY

L_UOM n n n n n

L_TAXAMT n

L_TAXRATE n n n n n

L_CARRIERSERVICELEV

ELCODE n

L_COST n

Description

(Optional) Alternate tax rate for this item.

Character length and limitations: 4 numeric characters plus decimal: XX.XX

(Optional) Alternate tax identifier for this item.


(Optional) Extended item amount.








(Optional) Total line item amount including tax. + for debit, - for credits



(Optional) Item’s supplier stock keeping unit (SKU) number or product code.




(Optional) Service code.

Character length and limitations: 1 alphanumeric character

(Optional) Item freight amount.


(42.00, not 42) and exclude comma separators (1234.56 not 1,234.56). Examples: tip=3.00, convenience charge=2.00. 10 currency characters



(Optional) Item tax amount.



(Optional) Tax rate for this item.

Character length and limitations: 4 numeric characters plus decimal:XXXX


C




D

VERBOSITY: Viewing Processor-

Specific Transaction Results

Set the VERBOSITY parameter to HIGH to view the processor’s raw response values and additional values. This setting returns multiple parameters. Select only the returned parameters that you want to handle and disregard the rest.

NOTE

:

VERBOSITY

is being deprecated in future Gateway releases.


D

VERBOSITY: Viewing Processor-Specific Transaction Results


E

ISO Country Codes

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

NOTE

: If PayPal is your acquirer, refer instead to the

“Countries and Regions Supported by

PayPal” on page 225

.


E

ISO Country Codes


F

Codes Used by FDMS South Only

The following codes are used by FDMS South only.



“MasterCard Country Codes for FDMS South Only” on page 203





“Visa Country Codes” on page 210

“Units of Measure” on page 217

MasterCard Country Codes for FDMS South Only

ALBANIA ALB

ALGERIA DZA

AMERICAN SAMOA ASM

ANDORRA AND

ANGOLA AGO

ANGUILLA AIA

ANTARCTICA ATA

ANTIGUA ATG

APHGANISTAN AFG

ARGENTINA ARG

ARMENIA ARN

ARUBA ABW

AUSTRALIA AUS

AUSTRIA AUT

AZERBAIJAN AZE

BAHAMAS BHS

BAHRAIN BHR

BANGLADESH

BARBADOS

BGD

BRB

BELARUS BLR

BELGIUM BEL


204

F

Codes Used by FDMS South Only

MasterCard Country Codes for FDMS South Only

BELIZE BLZ

BENIN BEN

BERMUDA BMU

BHUTAN BTN

BOLIVIA BOL

BOSNIA AND HERZEGOVINA BIH

BOTSWANA BWA

BOUVET ISLAND BVT

BRAZIL BRA

BRITISH INDIAN OCEAN TERRITORY IOT

BRUNEI BRN

BULGARIA BGR

BURKINA FASO BFA

BURUNDI

CAMBODIA

BDI

KHM

CANADA CAN

CAPE VERDE CPV

CAYMAN ISLANDS

CENTRAL AFRICAN REPUBLIC

CYM

CAF

CHAD TCD

CHILE CHL

CHINA CHN

CHRISTMAS ISLAND CXR

CMEROON, UNITED REP.

COCOS (KEELING) ISLANDS

CMR

CCK

COLOMBIA COL

COMOROS COM

CONGO GOG

COOK ISLANDS COK

COSTA RICA

COTED’IVOIRE

CROATIA

CRI

CIV

HRV




F

CYPRUS CYP

CZECH REPUBLIC CZE

DENMARK DNK

DJIBOUTI DJI

DOMINICA DMA

DOMINICAN REPUBLIC

EL SALVADOR

DOM

SLV

EQUATORIAL GUINEA GNQ

ESTONIA EST

ETHIOPIA

FAEROE ISLANDS

ETH

FRO

FALKLAND ISLANDS (MALVINAS)

FIJI

FLK

FJI

FINLAND FIN

FRANCE FRA

FRENCH GUIANA

FRENCH POLYNESIA

GUF

PYF

FRENCH SOUTHERN TERRITORIES ATF

GABON GAB

GAMBIA GMB

GEORGIA GEO

GERMAN DEMOCRATIC REP DDR

GERMANY DEU

GHANA GHA

GIBRALTAR GIB

GREECE GRC

GREENLAND GRL

GRENADA GRD

GUADALUPE GLP

GUAM GUM

GUATEMALA GTM

GUINEA GIN


206

F



GUINEA-BISSAU GNB

GUYANA GUY

HAITI HTI

HEARD AND MCDONALD ISLANDS HMD

HONDURAS HND

HONG KONG HKG

HUNGARY HUN

ICELAND ISL

INDIA IND

INDONESIA IDN

IRAN IRN

IRAQ IRQ

IRELAND IRL

ISRAEL ISR

ITALY ITA

JAMAICA JAM

JAPAN JPN

JORDAN JOR

KAZAKHSTAN KAZ

KENYA KEN

KOREA, REPUBLIC OF KOR

KUWAIT KWT

KYRGYZSTAN KGZ

LAO PEOPLES DEMOCRATIC LAO

LATVIA LVA

LEBANON LBN

LESOTHO LSO

LIBERIA LBR

LIBYAN ARAB JAMAHIRIYA LBY

LIECHTNSTIEN LIE

LITHUANIA LTU

LUXEMBOURG LUX




F

MACAU MAC

MALAYSIA MYS

MALDIVES MDV

MALI MLI

MALTA MLT

MANACO

MARSHALL ISLANDS

MCO

MHL

MARTINIQUE MTQ

MAURITANIA MRT

MAURITIUS MUS

MEXICO MEX

MICRONESIA FSM

MOLDOVA MDA

MONGOLIA MNG

MONTSERRAT MSR

MOROCCO MAR

MOZAMBIQUE MOZ

MYANMAR MMR

NAMIBIA NAM

NAURU NRU

NEGEL SEN

NEPAL NPL

NETHERLANDS NLD

NETHERLANDS ANTILLES

NEW CALEDONIA

ANT

NCL

NEW ZEALAND NZL

NICARAGUA NIC

NIGER NER

NIGERIA NGA

NIUE

NORFOLK ISLAND

NORTHERN MARIANA ISLAND

NIU

NFK

MNP


208

F



NORWAY NOR

OMAN OMN

PAKISTAN PAK

PALAU PLW

PANAMA PAN

PAPUA NEW GUINEA PNG

PARAGUAY PRY

PERU PER

PHILIPPINES PHI

PITCAIRN ISLAND PCN

POLAND POL

PORTUGAL PRT

PUERTO RICO PRI

QATAR QAT

REUNION REU

ROMANIA ROM

RUSSIAN FEDERATION RUS

RWANDA

SAMOA

RWA

WSM

SAN MARINO

SAN TOME AND PRICIPEL

SMR

STP

SAUDI ARABIA SAU

SEYCHELLES SYC

SIERRA LEONA SLE

SINGAPORE SGP

ST. HELENA

ST. KITTS-NEVIS-ANGUILLA

SHN

KNA

ST. LUCIA

ST. PIERRE AND MIQUELON

LCA

SPM

ST. VINCENT AND THE GRENADINES VCT

SUDAN SDN

SURINAME SUR




F

SVALBARD AND JAN MAYEN ISLANDS SJM

SWAZILAND SWZ

SWEDEN SWE

SWITZERLAND

SYRIAN ARAB REPUBLIC

CHE

SYR

TAIWAN, PROVIDENCE OF CHINA TWN

TAJIKISTAN TJK

TANZANIA, UNITED REPUBLIC TZA

THAILAND THA

TOGO TGO

TOKELAU TKL

TONGA TON

TRINIDAD AND TOBAGO TTO

TUNISIA TUN

TURKEY TR

TURKMENISTAN TM

TURKS AND CAICOS ISLANDS TC

TUVALU TUV

U.S. MINOR OUTLYING ISL.

UMI

UGANDA UGA

UKRAINE UKR

UNITED ARAB EMIRATES

UNITED KINGDOM

ARE

GBR

UNITED STATES USA

URUGUAY URY

UZBEKISTAN UZB

VANUATU VUT

VATICAN CITY STATE VAT

VENEZUELA VEN

VIETNAM

VIRGIN ISLANDS BRITISH

VIRGIN ISLANDS US

VNM

VGB

VIR


F


Visa Country Codes

WALLIS AND FUTUNA IS WLF

WESTERN SAHARA ESH

YEMEN YEM

YUGOSLAVIA YUG

ZAIRE ZAR

ZAMBIA ZMB

ZIMBABWE RHO

210

Visa Country Codes

ALBANIA AL

ALGERIA DZ

AMERICAN SAMOA AS

ANDORRA AD

ANGOLA AO

ANGUILLA AI

ANTARCTICA AQ

ANTIGUA AG

APHGANISTAN AF

ARGENTINA AR

ARMENIA AM

ARUBA AW

AUSTRALIA AU

AUSTRIA AT

AZERBAIJAN AZ

BAHAMAS BS

BAHRAIN BH

BANGLADESH

BARBADOS

BD

BB

BELARUS BY

BELGIUM BE


BELIZE BZ

BENIN BJ

BERMUDA BM

BHUTAN BT

BOLIVIA BO

BOSNIA AND HERZEGOVINA BA

BOTSWANA BW

BOUVET ISLAND BV

BRAZIL BR

BRITISH INDIAN OCEAN TERRITORY IO

BRUNEI BN

BULGARIA BG

BURKINA FASO BF

BURUNDI

CAMBODIA

BI

KH

CANADA CA

CAPE VERDE CV

CAYMAN ISLANDS

CENTRAL AFRICAN REPUBLIC

KY

CF

CHAD TD

CHILE CL

CHINA CN

CHRISTMAS ISLAND CX

CMEROON, UNITED REP.

CM

COLOMBIA CO

COMOROS KM

CONGO CG

COOK ISLANDS

COSTA RICA

COTED’IVOIRE

CROATIA

CK

CR

CI

HR

CYPRUS CY

Gateway Developer Guide and Reference 31 July 2012



F

211

212

F



CZECH REPUBLIC CZ

DENMARK DK

DJIBOUTI DJ

DOMINICA DM

DOMINICAN REPUBLIC DO

EAST TIMOR

ECUADOR

TP

EC

EGYPT

EL SALVADOR

EG

SV

EQUATORIAL GUINEA GQ

ESTONIA EE

ETHIOPIA

FAEROE ISLANDS

FALKLAND ISLANDS (MALVINAS)

FIJI

ET

FK

FK

FJ

FINLAND FI

FRANCE FR

FRENCH GUIANA

FRENCH METROPOLITAN

GF

FX

FRENCH POLYNESIA

FRENCH SOUTHERN TERRITORIES

PF

TF

GABON GA

GAMBIA GM

GEORGIA GE

GERMANY DE

GHANA GH

GIBRALTER GI

GREECE GR

GREENLAND GL

GRENADA GD

GUADALUPE GP

GUAM GU


GUATEMALA GT

GUINEA GN

GUINEA-BISSAU GW

GUYANA GY

HAITI HT

HEARD AND MCDONALD ISLANDS HM

HONDURAS HN

HONG KONG HK

HUNGARY HU

ICELAND IS

INDIA IN

INDONESIA ID

IRAN IR

IRAQ IQ

IRELAND IE

ISRAEL IL

ITALY IT

JAMAICA JM

JAPAN JP

JORDAN JO

KAZAKHSTAN KZ

KENYA KE

KIRIBATI KI

KOREA, REPUBLIC OF KR

KUWAIT KW

KYRGYZSTAN KG

LAO PEOPLES DEMOCRATIC LA

LATVIA LV

LEBANON LB

LESOTHO LS

LIBERIA LR

LIBYAN ARAB JAMAHIRIYA LY




F

213

214

F



LIECHTNSTIEN LI

LITHUANIA LT

LUXEMBOURG LU

MACAU

MACEDONIA

MADAGASCAR

MALAWI

MO

MK

MG

MW

MALAYSIA MY

MALDIVES MV

MALI ML

MALTA MT

MANACO

MARSHALL ISLANDS

MC

MH

MARTINIQUE MQ

MAURITANIA MR

MAURITIUS MU

MAYOTTE YT

MEXICO MX

MICRONESIA FM

MOLDOVA MD

MONGOLIA MN

MONTSERRAT MS

MOROCCO MA

MOZAMBIQUE MZ

MYANMAR MM

NAMIBIA NA

NAURU NR

NEPAL NP

NETHERLANDS NL

NETHERLANDS ANTILLES

NEW CALDONIA

NEW ZEALAND

AN

NC

NZ


NICARAGUA NI

NIGER NE

NIGERIA NG

NIUE

NORFOLK ISLAND

NU

NF

NORTHERN MARIANA ISLAND MP

NORWAY NO

OMAN OM

PAKISTAN PK

PALAU PW

PANAMA PA

PAPUA NEW GUINEA PG

PARAGUAY PY

PERU PE

PHILIPPINES PH

PITCAIRN ISLAND PN

POLAND PL

PORTUGUL PT

PUERTO RICO PR

QATAR QA

REUNION RE

ROMANIA RO

RUSSIAN FEDERATION RU

RWANDA

SAMOA

SAN MARINO

SAN TOME AND PRICIPEL

SAUDI ARABIA

SENEGAL

SA

SN

SEYCHELLES SC

SIERRA LEONA SL

SINGAPORE SG

RW

WS

SM

ST




F

215

216

F



ST. HELENA

ST. KITTS-NEVIS-ANGUILLA

ST. LUCIA

ST. PIERRE AND MIQUELON

ST. VINCENT AND THE GRENADINES

PM

VC

SUDAN SD

SURINAME SR

SH

KN

LC

SVALBARD AND JAN MAYEN IS SJ

SWAZILAND SZ

SWEDEN

SWITZERLAND

SE

CH

SYRIAN ARAB REPUBLIC

TAIWAN, PROVIDENCE OF CHINA

SY

TW

TAJIKISTAN TJ

TANZANIA, UNITED REPUBLIC TZ

THAILAND TH

TOGO TG

TOKELAU TK

TONGA TO

TRINIDAD AND TOBAGO TT

TUNISIA TN

TURKEY TR

TURKMENISTAN TM

TURKS AND CAICOS ISLANDS TC

TUVALU TV

U.S. MINOR OUTLYING ISL.

UM

UGANDA UG

UKRAINIAN SSR

UNITED ARAB EMIRATES

UNITED KINGDOM

UNITED STATES

UA

AE

GB

US

URUGUAY UY


UZBEKISTAN UZ

VANUATU VU

VATICAN CITY STATE VA

VENEZUELA VE

VIETNAM VN

VIRGIN ISLANDS BRITISH

VIRGIN ISLANDS US

VG

VI

WALLIS AND FUTUNA IS

WESTERN SAHARA

WF

EH

YEMEN YE

YUGOSLAVIA YU

ZAIRE ZR

ZAMBIA ZM

ZIMBABWE ZW

Units of Measure

Acre (4840 yd2)

Alcoholic strength by mass

Alcoholic strength by volume

Ampere*

Ampere=hour (3,6 kC)*

Are (100 m2)

Bar*

Barrel (petroleum) (158,987 dm3)

Becquerel*

Billion EUR

Billion US

Board foot

Brake horse power (245,7 watts)

British thermal unit (1,055 kilojoules)

BQL

BIL

MLD

BFT

BHP

BTU

ACR

ASM

ASV

AMP

AMH

ARE

BAR

BLL



Units of Measure

F

217

218

F


Units of Measure

Bushel (35,2391 dm3)

Bushel (36,36874 dm3)

Candela*

Carrying capacity in metric tonnes

Cental GB (45,359237 kg)

Center, metric (100 kg) (syn.: Hectokilogram)

Centigram*

Centilitre*

Centimetre*

Cord (3,63 m3)

Coulomb per kilogram*

Coulomb*

Cubic centimetre*

Cubic decimetre*

Cubic foot

Cubic inch

Cubic metre per hour*

Cubic metre per second*

Cubic metre*

Cubic millimetre*

Cubic yard

Curie

Day*

Decade (ten years)

Decare

Decilitre*

Decimetre*

Decitonne*

Degree Celsius

Degree Fahrenheit

Degree Kelvin: Kelvin

Displacement tonnage

31 July 2012

DEC

DAA

DLT

DMT

DTN

CEL

FAH

INQ

MQH

MQS

MTQ

MMQ

YDQ

CUR

DAY

CLT

CMT

WCD

CKG

COU

CMQ

DMQ

FTQ

BUA

BUI

CDL

CCT

CNT

DTN

CGM

DPT


Dozen

Dozen packs

Dozen pairs

Dozen pieces

Dozen rolls

Drachm GB (3,887935 g)

Dram GB (1,771745 g)

Dram US (3,887935 g)

Dry Barrel (115,627 dm3)

Dry gallon (4,404884 dm3)

Dry pint (0,55061 dm3)

Dry quart (1,101221 dm3)

Farad*

Fluid ounce (28,413 cm3)

Fluid ounce (29,5735 cm3)

Foot (0,3048 m)

Gallon (4,546092 dm3)

Gigabecquerel*

Gigawatt-hour (1 million kW/h)*

Gill (0,142065 dm3)

Gill (11,8294 cm3)

Grain GB, US (64,798910 mg)

Gram of fissile isotopes

Gram*

Great gross (12 gross)

Gross

Gross (register) ton

Half year (six months)

Hectare

Hectobar*

Hectogram*

Hectokilogram*


GRM

GGR

GRO

GRT

SAN

HAR

HBA

HGM

DTH

FOT

GLI

GBQ

GWH

GII

GIA

GRN

GFI

DRA

BLD

GLD

PTD

QTD

FAR

OZI

OZA

DZN

DZP

DZR

DCP

DRL

DRM

DRI

31 July 2012


Units of Measure

F

219

220

F


Units of Measure

Hectolitre of pure alcohol

Hectolitre*

Hectometre*

Hertz*

Hour*

Hundred

Hundred boxes

Hundred international units

Hundred leaves

Hundred packs

Hundredweight US (45,3592 kg)

Inch (25,4 mm)

Joule*

Kelvin*

Kilobar*

Kilogram of caustic potash

Kilogram of caustic soda

Kilogram of named substance

Kilogram of nitrogen

Kilogram of phosphonic anhydride

Kilogram of phosphorus pentoxide

Kilogram of potassium hydroxide

Kilogram of potassium oxide

Kilogram of sodium hydroxide

Kilogram of substance 90 percent dry

Kilogram per cubic meter*

Kilogram per second*

Kilogram*

Kilohertz*

Kilojoule*

Kilometre per hour*

Kilometre*

31 July 2012

KSH

KSD

KMQ

KGS

KGM

KHZ

KJO

KMH

KMT

KPP

KPP

KPH

KPO

KPH

KSH

KNS

KNI

HIU

CLF

CNP

CWA

INH

JOU

KEL

KBA

HPA

HLT

HMT

HTZ

HUR

CEN

BHX


Kilopascal*

Kilorgram of uranium

Kilotonne*

Kilovar

Kilovolt*

Kilovolt-ampere*

Kilowatt*

Kilowatt-hour*

Knot (1 nautical mile per hour)

Leaf

Liquid gallon (3,78541 dm3)

Liquid pint (0,473176 dm3)

Liquid quart (0,946353 dm3)

Litre (1 dm3)*

Litre of pure alcohol

Long ton GB, US (1,0160469 t)

(long) hundredweight GB (50,802345 kg)

Lumen*

Lux

Megahertz*

Megalitre*

Megametre*

Megapascal*

Megavolt-ampere (1000 KVA)*

Megawatt*

Megawatt-hour (100 kW/h)*

Metre per second squared*

Metre per second*

Metre*

Metric carat (200 mg=2,10-4 kg)

Metric ton (1000 kg)

Milliard


MVA

MAW

MWH

MSK

MTS

MTR

CTM

TNE

MLD

LTN

CWI

LUM

LUX

MHZ

MAL

MAM

MPA

PTL

QTL

LTR

LPA

KWH

KNT

LEF

GLL

KPA

KUR

KTN

KVR

KVT

KVA

KWT

31 July 2012


Units of Measure

F

221

222

F


Units of Measure

Millibar*

Millicurie

Milligram*

Millilitre*

Millimetre*

Million

Million cubic metres*

Million international units

Minute*

Month

Nautical mile (1852 m)

Net (register) ton

Newton*

Number

Number of articles

Number of bobbons

Number of cells*

Number of international units

Number of packs

Number of pairs

Number of parcels

Number of parts

Number of rolls

Ohm*

Ounce GB, US (28,349523 g)

Ounce GB, US (31,103448 g) (syn: Troy ounce)

Pascal*

Pennyweight GB, US (1555174 g)

Piece

Pint (0,568262 dm3)

Pound GB, US (0,45359237 kg)

Proof gallon

31 July 2012

OHM

ONZ

APZ

PAL

DWT

PCE

PTI

LBR

PGL

NBB

NCL

NIU

NMP

NMR

NPL

NPT

NRL

MIU

MIN

MON

NMI

NTT

NEW

NMB

NAR

MBR

MCU

MGM

MLT

MMT

MIO

HMQ


Quart (1,136523 dm3)

Quarter (of a year)

Quarter, GB (12,700586 kg)

Quintal, metric (100 kg)

Revolution per minute*

Revolution per second*

Score scruple, GB (1,2955982 g)

Second*

Set

Shipping ton

Short standard (7200 matches)

Short ton GB, US (0,90718474 t)

Siemens*

Square centimetre*

Square decimetre*

Square foot

Square inch

Square kilometre*

Square metre*

Square mile

Square millimetre*

Square yard

Standard standard atmosphere (101325 Pa)

(statue) mile (1609,344 m)

Stone GB (6,350293 kg)

Technical atmosphere (98066,5 Pa)

Ten days

Ten pairs

Thousand

Thousand ampere-hour*


WSD

ATM

SMI

STI

ATT

DAD

TPR

MIL

TAH

DMK

FTK

INK

KMK

MTK

MIK

MMK

YDK

SCR

SEC

SET

SHT

SST

STN

SIE

CMK

QTI

QAN

QTR

DTN

RPM

RPS

SCO

31 July 2012


Units of Measure

F

223

F


Units of Measure

Thousand board feet (2,36 m3)

Thousand cubic metres per day*

Thousand standard brick equivalent

Ton of steam per hour

Tonne (1000 kg)*

Tonne of substance 90 percent dry

Trillion EUR

Trillion US

Troy ounce

Troy pound, US (373,242 g)

Volt*

Watt*

Watt-hour*

Weber

Week

Yard (0,9144 m)

Year

BIL

APZ

LBT

VLT

WTT

WHR

WEB

WEE

YRD

ANN

MBF

TQD

MBE

TSH

TNE

TSD

TRL


G

PayPal Acquirer

If PayPal is your acquirer and no other bank is involved in processing your transactions, use the following PayPal specific codes.

Countries and Regions Supported by PayPal

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

For a complete list of countries and regions supported by PayPal and their 2-character ISO-

3166-1 codes, please refer to the PayPal API reference list of Countries and Regions .

PayPal Currency Codes

PayPal uses 3-character ISO-4217 codes for specifying currencies in fields and variables.

Please refer to the Currency Codes section of the PayPal API reference for a complete list of currencies supported by PayPal.


G

PayPal Acquirer

PayPal Currency Codes


H

Additional Processor Information

Moneris Solutions

The Moneris Solutions processor has the following characteristics:



It supports ecommerce and mail order or telephone order (MOTO) transactions.





It supports the four basic credit card types: American Express, Discover, MasterCard, and

Visa.

To process live transactions, it requires undergoing a certification process. For details, see the Moneris Receipts Specification available on the PayPal developer website.


Additional Processor Information

Moneris Solutions


I

Payflow Link Migration

If you are currently using the legacy Payflow Link HTML input tag integration and you would like to use the name-value pair integration, you will need to contact PayPal Merchant

Technical Support to request your account to be upgraded to the new version of Payflow.

Before you request an upgrade, it is important that you understand the differences between the

Payflow Link legacy parameters and the equivalent Payflow parameters . Once you upgrade

your account to the new version your old legacy integration will still work. However, to take advantage of the new features we recommend that you update your Payflow Link integration and use equivalent Payflow parameters instead of the legacy Payflow Link HTML input tags.

Migrating from a legacy Payflow Link Integration

The legacy Payflow Link integration is now deprecated. It is recommended that you upgrade the version of your Payflow Link account which allows you to perform a broader set of functions. This upgrade allows you to switch from using the legacy Payflow Link HTML input tag parameters to using Payflow parameters. The table below lists legacy Payflow Link parameters and their Payflow equivalents.

Payflow Link legacy parameters and the equivalent Payflow parameters

Payflow Link Legacy Parameter Payflow Parameter

ADDRESS BILTOSTREET

ADDRESSTOSHIP

AMOUNT

AVSDATA

CARDNUM

CITY

CITYTOSHIP

COMMENT1

COMMENT2

COUNTRY

COUNTRYTOSHIP

COUNTRYCODE

CSC

SHIPTOSTREET

AMT

AVSADDR

and AVSZIP

ACCT

BILLTOCITY

SHIPTOCITY

COMMENT1

COMMENT2

BILLTOCOUNTRY

SHIPTOCOUNTRY

COUNTRYCODE

CVV2


230

I

Payflow Link Migration

Migrating from a legacy Payflow Link Integration

Payflow Link Legacy Parameter

CSCMATCH

CUSTID

DESCRIPTION

DLNUM

EMAIL

EMAILTOSHIP

EXPDATE

FAX

FAXTOSHIP

FIRSTNAME

INVOICE

LASTNAME

LOGIN

METHOD

NAME

NAMETOSHIP

PARTNER

PHONE

PHONETOSHIP

PONUM

SHIPAMOUNT

STATE

STATETOSHIP

TAX

TYPE

USER1 - USER10

ZIP

ZIPTOSHIP

Payflow Parameter

CVV2MATCH

CUSTID

N/A

DLNUM

BILLTOEMAIL

SHIPTOEMAIL

EXPDATE

BILLTOFAX

SHIPTOFAX

BILLTOFIRSTNAME

INVNUM

BILLTOLASTNAME

VENDOR

TENDER

BILLTOFIRSTNAME

BILLTOLASTNAME

SHIPTOFIRSTNAME

SHIPTOLASTNAME

PARTNER

BILLTOPHONENUM

SHIPTOPHONENUM

PONUM

FREIGHTAMT

BILLTOSTATE

SHIPTOSTATE

TAXAMT

TRXTYPE

USER

BILLTOZIP

SHIPTOZIP
