VeriSign Payment Services

Transcription

1 DEVELOPER S GUIDE VeriSign Payment Services Payflow Pro Developer s Guide VeriSign, Inc /Rev. 3

2 VeriSign Payment Services Payflow Pro Developer s Guide Copyright VeriSign, Inc. All rights reserved. The information in this document belongs to VeriSign. It may not be used, reproduced or disclosed without the written approval of VeriSign. DISCLAIMER AND LIMITATION OF LIABILITY VeriSign, Inc. has made efforts to ensure the accuracy and completeness of the information in this document. However,VeriSign, Inc. makes no warranties of any kind (whether express, implied or statutory) with respect to the information contained herein.verisign, Inc. assumes no liability to any party for any loss or damage (whether direct or indirect) caused by any errors, omissions, or statements of any kind contained in this document. Further, VeriSign, Inc. assumes no liability arising from the application or use of the product or service described herein and specifically disclaims any representation that the products or services described herein do not infringe upon any existing or future intellectual property rights. Nothing herein grants the reader any license to make, use, or sell equipment or products constructed in accordance with this document. Finally, all rights and privileges related to any intellectual property right described herein are vested in the patent, trademark, or service mark owner, and no other person may exercise such rights without express permission, authority, or license secured from the patent, trademark, or service mark owner. VeriSign Inc. reserves the right to make changes to any information herein without further notice. TRADEMARKS VeriSign, the VeriSign logo, VeriSign Intelligence and Control Services, VeriSign Trust Network, Go Secure!, OnSite, and other trademarks, service marks, and logos are registered or unregistered trademarks of VeriSign and its subsidiaries in the United States and in foreign countries. Other trademarks and service marks in this document are the property of their respective owners. This document supports VeriSign Payment Services 4 and all subsequent releases unless otherwise indicated in a new edition or release notes. This document may describe features and/or functionality that are not present in your software or your service agreement. Contact your account representative to learn more about what is available with this VeriSign product. If you need help using this product, contact customer support. [email protected] Publication date: March 2005 ii VeriSign, Inc /Rev. 3

3 Summary of Revisions Summary of Revisions VeriSign Payment Services Payflow Pro Developer s Guide VeriSign, Inc /Rev. 3 The following changes were made to this document since the last version: Throughout document Chapter 2, Installing and Configuring the Payflow Pro APIs Chapter 3, Performing Credit Card Transactions Chapter 4, Responses to Credit Card Transaction Requests Updated document cover and page layout. Added Support for FDMS North processor. Added support for AMEX APAC processor. Changed the parameter name SHIPTOCOUNTRY to the correct name, COUNTRYCODE. Identified certification versions supported by the SDK. Added TRANSSTATE to the verbosity settings in Table 3-3 on page 24. Updated the list of fields that are copied in credit transactions. Added two new RESULT codes (150 and 151) to Table 4-2 on page 48. Redefined the format of a PNREF value (Payflow Pro), also referred to as a Transaction ID value (Payflow Link), to more accurately reflect the flexibility of its design to support future expansion. See PNREF Format on page 47. VeriSign, Inc /Rev. 2 The following changes were made to this document since the last revision. Tax exempt Purchasing card transactions The usage of the TAXAMT and TAXEXEMPT values in marking transactions as exempt from tax has been clarified. See Appendix D, Submitting Purchasing Card Level 2 and Level 3 Transactions. VeriSign, Inc /Rev. 3 iii

4 VeriSign Payment Services Payflow Pro Developer s Guide iv VeriSign, Inc /Rev. 3

5 DEVELOPER S GUIDE Contents + Summary of Revisions iii + Chapter 1 Introduction About Payflow Pro How Payflow Pro Works Payflow Pro Advantages Pre-integrated Solutions Supported Processing Platforms Supported Credit Cards Accepting a New Credit Card Type Supported Payment Types Payflow Recurring Billing Service Customer Support VeriSign Payment Services Processor Contact Information: Transaction Settlement About this Document Related Document About Security VeriSign, Inc /Rev. 3 v

6 VeriSign Payment Services Payflow Pro Developer s Guide + Chapter 2 Installing and Configuring the Payflow Pro APIs Before You Begin Supported Platforms Preparing the Payflow Pro Client Application Chapter 3 Performing Credit Card Transactions 13 About Credit Card Processing Obtaining an Internet Merchant Account Planning Your Payflow Pro Integration E-commerce Indicator (ECI) Credit Card Transaction Format Command Syntax Guidelines Parameters Used in Credit Card Transactions Viewing Processor-specific Transaction Results: Verbosity Supported Verbosity Settings Changing the Verbosity Setting Values Required by All Transaction Types Submitting Sale Transactions Additional Required Parameters for Sale Transactions Example Sale Transaction Parameter List Submitting Credit Transactions Additional Required Parameters for Credit Transactions Fields Copied From the Original Transaction into the Credit Transaction Example Credit Transaction Parameter List Submitting Void Transactions Additional Required Parameters for Void Transactions Fields Copied From the Original Transaction into the Void Transaction Example Void Transaction Parameter List Submitting Voice Authorization Transactions Additional Required Parameters for Voice Authorization Transactions vi VeriSign, Inc /Rev. 3

7 Contents Example Voice Authorization Transaction Parameter List Submitting Inquiry Transactions Using the PNREF to Perform Inquiry Transactions Using the CUSTREF to Perform Inquiry Transactions Example Inquiry Transaction Parameter List, Using the CUSTREF Submitting Authorization/Delayed Capture Transactions Additional Required Parameters for Authorization Transactions Additional Required Parameters for Delayed Capture Transactions Fields Copied From the Authorization Transaction into the Delayed Capture Transaction Delayed Capture Transaction: Capturing Transactions for Lower Amounts Delayed Capture Transaction: Capturing Transactions for Higher Amounts Delayed Capture Transaction: Error Handling and Retransmittal Submitting Purchasing Card Transactions Submitting Reference Transactions Transaction Types that can be Used as the Original Transaction Fields Copied From Reference Transactions Example Reference Transaction Using Address Verification Service (AVS) Processing Platforms Supporting AVS Example AVS Request Parameter List Example AVS Response Card Security Code (CSC) Validation Processing Platforms and Credit Cards Supporting CSC CSC Results Example CVV2 Request Example CVV2MATCH Response Submitting Card-Present (Swipe) Transactions VeriSign, Inc /Rev. 3 vii

8 VeriSign Payment Services Payflow Pro Developer s Guide Supported Processing Platforms Card-present Transaction Syntax Example Card-present Transaction Parameter List Logging Transaction Information Chapter 4 Responses to Credit Card Transaction Requests 45 Contents of a Response to a Credit Card Transaction Request PNREF Value PNREF Format RESULT Codes and RESPMSG Values RESULT Values for Transaction Declines or Errors RESULT Values for Communications Errors Chapter 5 Testing Payflow Pro Credit Card Transactions 55 Testing Guidelines Credit Card Numbers Used for Testing Testing Result Codes Responses VeriSign Result Codes Returned Based on Transaction Amount Alternative Methods for Generating Specific Result Codes Testing Address Verification Service (AVS) Testing Card Security Code (CVV2) Testing TeleCheck Transactions Chapter 6 Activating Your Payflow Account Appendix A Processors Requiring Additional Transaction Parameters65 American Express Additional Credit Card Parameters, American Express First Data Merchant Services (FDMS) Nashville Additional Credit Card Parameters, FDMS Nashville viii VeriSign, Inc /Rev. 3

9 Contents First Data Merchant Services (FDMS) North First Data Merchant Services (FDMS) South Additional Credit Card Parameters, FDMS South Nova Additional Credit Card Parameters, Nova Paymentech Additional Credit Card Parameters, Paymentech Vital Additional Credit Card Parameters, Vital Appendix B Performing TeleCheck Electronic Check Transactions75 TeleCheck Contact Information TeleCheck Transaction Syntax Command Syntax Guidelines TeleCheck Parameters Required Parameters Testing TeleCheck Transactions Test Transaction Server Example Test Transaction Preparing for TeleCheck Production Transactions. 81 Logging Transaction Information Appendix C Responses to TeleCheck Transaction Requests HOSTCODE Values Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions About Purchasing Cards About Program Levels Accepted BIN Ranges Performing American Express Purchasing Card Transactions Through the American Express Processor Supported Transaction Types Avoiding Downgrade VeriSign, Inc /Rev. 3 ix

10 VeriSign Payment Services Payflow Pro Developer s Guide Submitting Successful Level 3 Transactions Edit Check Accepted BIN Ranges American Express Level 2 Transaction Data Example American Express Level 2 Transaction Parameter List American Express Level 3 Transaction Data Example American Express Level 3 SDK Transaction Parameter List Example American Express Level 3 XMLPay Transaction Performing Purchasing Card Transactions, First Data Merchant Services (FDMS) Nashville Performing Purchasing Card Transactions, First Data Merchant Services (FDMS) North Purchase Card Line Item Parameters, FDMS North Performing Purchasing Card Transactions, First Data Merchant Services (FDMS) South Purchase Card Line Item Parameters, FDMS South FDMS South Purchase Card Level 2 and 3 Example Parameter List FDMS South Line Item Parameter Example Performing Purchasing Card Transactions, Global Payments - Central Global Payments - Central Level 2 Parameters. 107 Example Global Payments - Central Level 2 Visa or MasterCard Transaction Parameter List Performing Purchasing Card Transactions, Global Payments - East Global Payments - East Level 2 Parameters Example Global Payments - East Level 2 Visa or MasterCard Transaction Parameter List Performing Purchasing Card Transactions, Nova. 108 Nova Level 2 Parameters Additional Parameters, Nova Example Nova Level 2 Transaction Parameter List Performing Level 2 Purchasing Card Transactions, Paymentech x VeriSign, Inc /Rev. 3

11 Contents Paymentech Level 2 Parameters Example Paymentech Level 2 Transactions Performing Level 2 Purchasing Card Transactions, Vital Vital Level 2 Transaction Data Example Vital Level 2 Visa Transaction Parameter List Performing Level 3 Purchasing Card Transactions, Paymentech Paymentech Level 2 Transaction Data (Required for Level 3) Paymentech Level 3 MasterCard Transaction Data Paymentech Level 3 Visa Transaction Data Example Paymentech Level 3 Transaction Parameter Lists Performing Level 3 MasterCard Transactions, Vital Vital Level 2 MasterCard Transaction Data for Line-Item Transactions (Required for Level 3) 115 Vital Level 3 MasterCard Extended Data Vital Level 3 MasterCard Line-item Detail Records 118 Example Vital Level 3 MasterCard Transaction Parameter List Performing Level 3 Visa Transactions, Vital Vital Level 2 Visa Transaction Data for Line-Item Transactions (Required for Level 3) Vital Level 3 Visa Extended Data Vital Level 3 Visa Line-item Detail Records Example Vital Level 3 Visa Transaction Parameter List Appendix E Additional Reporting Parameters Appendix F XMLPay About XMLPay XMLPay 2.0 Core Specification Document VeriSign, Inc /Rev. 3 xi

12 VeriSign Payment Services Payflow Pro Developer s Guide + Appendix G ISO Country Codes Appendix H Codes Used by FDMS South Only.137 MasterCard Country Codes Visa Country Codes Units of Measure FDMS South Currency Codes and Decimal Positions Appendix I Ensuring Safe Storage and Use of Passwords155 Overview of the Risks Fraud Prevention Resources Overview of the Example Password Encryption Program Included Files Requirements Encrypting the Password Submitting Transactions Using the Encrypted Password Code Listings encrypt.pl Code Listing PFProEncrypt.java Code Listing securetest.pl Code Listing PFProSecure.java Code Listing Appendix J Frequently Asked Questions xii VeriSign, Inc /Rev. 3

13 rte Chap CHAPTER 1 1Introduction VeriSign Payflow Pro is a high performance TCP/IP-based Internet payment solution. Payflow Pro is pre-integrated with leading e-commerce solutions and is also available as a downloadable software development kit (SDK). About Payflow Pro The Payflow Pro client resides on your computer system and is available on all major Web server platforms in a variety of formats to support integration requirements. It is available as a C library (.dll/.so), binary executable, Java library, COM object, Java Native Interface, and Perl Module Interface. Payflow Pro is multi-threaded and allows multiple concurrent transactions from a single client. It can be integrated as a Web-based or a non-web-based application. It does not require the HTTP protocol to run, which allows for greater flexibility in configuration and reduced processing overhead for higher performance. How Payflow Pro Works Payflow Pro uses a client/server architecture to transfer transaction data from you to the processing networks, and then returns the authorization results to you. Payflow VeriSign, Inc /Rev. 3 1

14 VeriSign Payment Services Payflow Pro Developer s Guide Pro can process real-time credit card transactions and other transaction types to most of the financial processing centers in the United States. Merchant VeriSign Custom Web Applications Shopping Carts Bill Presentment Solutions Internet Enabled Legacy Systems TCP/IP SSL Merchant Payflow Pro software development kit Internet VeriSign Payflow payment gateway Figure 1-1 Payflow Pro transaction flow 1 The Payflow Pro client encrypts each transaction request using the latest Secure Sockets Layer (SSL) encryption and establishes a secure link with the VeriSign Payflow server over the Internet. 2 The VeriSign Payflow server, a multi-threaded processing environment, receives the request and transmits it (over a secure private network) to the appropriate financial processing network for real-time payment authorization. 3 The response (approved/declined, and so on) is received from the financial network and is returned in the same session to the Payflow Pro client. 4 The Payflow Pro client completes each transaction session by transparently sending a transaction receipt to the VeriSign server before disconnecting the session. The entire process is a real-time synchronous transaction. Once connected, the transaction is immediately processed and the answer returned in about three seconds. Payflow Pro does not affect or define the time periods of authorizations, nor does it influence the approval or denial of a transaction by the issuer. When integrating with Payflow Pro, you need only be concerned with passing all the required data for transaction authorization. For transactions that you want to be settled (close batch), the operation is handled by VeriSign. 2 VeriSign, Inc /Rev. 3

15 Chapter 1 Introduction Payflow Pro Advantages + Configurable to any e-commerce application. Payflow Pro is ideal for enterprise merchants who require complete customizability for a controlled buyer experience. + Easy to install and implement. Downloadable from VeriSign s Web site, Payflow Pro can be easily integrated into a customized e-commerce solution in a matter of hours. + Integration versatility. Payflow Pro can be integrated as an application library or can be run using CGI scripts. Pre-integrated Solutions Payflow Pro is integrated with the majority of third-party shopping carts and e-commerce applications. + For a list of shopping carts compatible with Payflow Pro, see shopping-cart-service-list.html + Some VeriSign integrations are included with the third-party solution. For a list of e-commerce applications compatible with Payflow Pro, see development-platform-partners.html + The following VeriSign integrations are available from VeriSign Manager s Download page ( BEA Weblogic IBM Websphere Payment Manager Macromedia Cold Fusion Microsoft Commerce Server 2000 and 2002 Miva Oracle ipayment VeriSign, Inc /Rev. 3 3

16 VeriSign Payment Services Payflow Pro Developer s Guide Supported Processing Platforms Payflow Pro supports the following processing platforms: American Express Phoenix American Express APAC First Data Merchant Services (FDMS) Nashville First Data Merchant Services (FDMS) North First Data Merchant Services (FDMS) South First Data Resources (FDR) Australia Global Payments Central Global Payments East Nova Paymentech New Hampshire First Data TeleCheck Vital Supported Credit Cards Payflow Pro supports multiple credit card types, including: American Express/Optima Diners Club Discover/Novus JCB MasterCard Visa Accepting a New Credit Card Type To accept a new credit card type, the Primary or Secondary Contact person for the Payflow account should follow these steps: 1 Contact your Acquiring bank (the merchant bank that holds your Internet Merchant Account) and ask them to add the new card type to your Internet Merchant account. If your account is partnered with American Express, you must first obtain a Visa/MasterCard merchant account to accept other card types. 2 When the Acquiring bank notifies you that you can accept the new card type, contact VeriSign Customer Support at Ask the representative to 4 VeriSign, Inc /Rev. 3

17 Chapter 1 Introduction add the new card type to your Payflow account. The representative will verify your identity and perform the update. IMPORTANT! For your security, VeriSign recommends that you keep your password secure and do not communicate it to others. VeriSign will never ask you for your password. Your account will start accepting the new card type in hours. Special Case: American Express Either the Primary or Secondary contact (listed under the Account Info section in VeriSign Manager) must your VeriSign login ID and the following processor setup information to [email protected]. Processor Setup Information + Merchant ID number / SE number. 9 to 11 digits + SIC (Category Code). 4 digits + Business Name. maximum 20 characters + Business City. maximum 18 characters + Business State. 2 characters Once VeriSign updates the information, you are notified by return and your account becomes active at the top of the next hour. VeriSign recommends that you test your account with a real credit card before allowing the public to use the new card type. Supported Payment Types Payflow Pro supports multiple payment types in a single installation, including: + Credit cards + Electronic check (TeleCheck) + Check cards + Purchasing cards (also referred to as commercial cards, corporate cards, procurement cards, or business cards) Level II and Level III + Automated Clearing House (ACH). For information on performing ACH transactions, contact your VeriSign Sales Representative at [email protected] VeriSign, Inc /Rev. 3 5

18 VeriSign Payment Services Payflow Pro Developer s Guide Payflow Recurring Billing Service VeriSign s Payflow Recurring Billing Service is a scheduled payment solution that enables you to automatically bill your customers at regular intervals for example, a monthly fee of $42 for 36 months with an initial fee of $129. You enroll separately for the Payflow Recurring Billing Service. Using Payflow Pro to define and manage recurring transactions is fully described in VeriSign Payflow Recurring Billing Service Guide for Payflow Pro. Customer Support For problems with transaction processing or your connection to VeriSign, contact: VeriSign Payment Services Online Information: ml Mail [email protected] VeriSign Payment Services Attn: Customer Support 487 E. Middlefield Rd. Mountain View, CA Phone Processor Contact Information: Transaction Settlement For questions regarding transaction settlement, contact your processor: American Express N. 31st Avenue Phoenix, AX (800) First Data Merchant Services (FDMS) Nashville First Data Corporation 2525 Perimeter Place Drive Suite 123 (800) VeriSign, Inc /Rev. 3

19 Chapter 1 Introduction First Data Merchant Services (FDMS) North First Data Merchant Services 1307 Walt Whitman Road Melville, New York First Data Merchant Services (FDMS) South First Data Corporation Business Payment Services Group 4000 Coral Ridge Drive Coral Springs, FL (800) Global Payments East Global Payments Inc. Four Corporate Square Atlanta, Georgia Main corporate number: Global Payments Central Global Payments Inc Westport Center Dr. St. Louis, MO (314) [email protected] Nova Information Systems, Inc. Knoxville Operations Center 7300 Chapman Highway Knoxville, TN (800) Paymentech, Inc. 4 Northeastern Blvd. Salem, NH (800) TeleCheck Merchant Services P.O. Box 4513 Houston, TX (800) (Merchant Services) VeriSign, Inc /Rev. 3 7

20 VeriSign Payment Services Payflow Pro Developer s Guide Vital Visanet Processing Services 8320 South Hardy Road Tempe, AZ (800) (Merchant Help Desk) Wells Fargo Bank Merchant Card Services 1200 Montego Way Walnut Creek, California About this Document This document is organized as follows: + Chapter 2, Installing and Configuring the Payflow Pro APIs, shows a typical Payflow Pro installation procedure for NT and UNIX. + Chapter 3, Performing Credit Card Transactions, discusses credit card transaction syntax and parameters and describes how to perform transactions. + Chapter 4, Responses to Credit Card Transaction Requests, describes the responses to credit card transaction requests. + Chapter 5, Testing Payflow Pro Credit Card Transactions, describes how to test your Payflow Pro integration for credit card transactions. + Chapter 6, Activating Your Payflow Account, specifies the steps you follow when you are ready to accept live transactions with Payflow Pro. + Appendix A, Processors Requiring Additional Transaction Parameters, lists processors and their processor-specific parameters. + Appendix B, Performing TeleCheck Electronic Check Transactions, discusses TeleCheck transaction syntax and parameters and describes how to perform transactions. In addition, this chapter describes testing your TeleCheck integration. + Appendix C, Responses to TeleCheck Transaction Requests, describes the responses to TeleCheck transaction requests. + Appendix D, Submitting Purchasing Card Level 2 and Level 3 Transactions. VeriSign Payment Services supports passing Purchasing Card Level 2 information (such as purchase order number, tax amount, and charge description) in the settlement file. 8 VeriSign, Inc /Rev. 3

21 Chapter 1 Introduction + Appendix E, Additional Reporting Parameters, details the parameters that can be passed to VeriSign for reporting purposes. + Appendix F, XMLPay, briefly describes XMLPay and tells where you may obtain a copy of VeriSign Payment Services XMLPay 2.0 Core Specification. + Appendix G, ISO Country Codes, lists Country Codes, Units of Measure, and Currency Codes. + Appendix H, Codes Used by FDMS South Only, lists codes used only by First Data Merchant Services (FDMS) South. + Appendix I, Ensuring Safe Storage and Use of Passwords, describes the example Payflow Pro Encrypted Password program. + Appendix J, Frequently Asked Questions, contains answers to the most commonly asked questions about Payflow Pro. Related Document VeriSign Manager User s Guide describes the use of VeriSign Manager the Web-based administration tool that you use to process transactions manually, issue credits, and generate reports. About Security It is your responsibility to protect your passwords and other confidential data and to implement security safeguards on your Web site and in your organization, or to ensure that your hosting company or internal Web operations team is implementing them on your behalf. You or your ISP/shopping cart provider should be able to adhere to security requirements as protective as those described at: VeriSign, Inc /Rev. 3 9

22 VeriSign Payment Services Payflow Pro Developer s Guide IMPORTANT! To enable you to test Payflow Pro, VeriSign provides sample transaction scripts that you customize with your VeriSign account information and password. Because the password is initially stored in the text of the program, it is vulnerable. Do not use VeriSign's test scripts in your production environment. To minimize fraud, machine passwords should always be encrypted. You must write a program that encrypts and decrypts your Payflow Pro account password. Appendix I, Ensuring Safe Storage and Use of Passwords, describes an example method for encrypting your Payflow Pro password and enabling your application to access and decrypt the password when submitting Payflow Pro transactions. 10 VeriSign, Inc /Rev. 3

23 rte Chap CHAPTER 2 2Installing and Configuring the Payflow Pro APIs The Payflow Pro software development kit (SDK) is available either as a standalone client that you can integrate with your Web store using CGI scripts or as a set of APIs for direct integration with your application. Note The functionality introduced in this version of the SDK is available only to clients using V3 certification. It is not backward compatible to earlier versions. This chapter provides instructions for downloading the SDK appropriate to your platform. IMPORTANT! Full API documentation is included with each SDK. Before You Begin If you plan to integrate the Payflow Pro APIs yourself: You should be familiar with Web development tools and procedures. If you are not, consider letting one of VeriSign s Web development partners help you. You can find a VeriSign Web development partner at: development-platform-partners.html If you require assistance integrating the Payflow Pro APIs: Consider using a shopping cart that integrates Payflow Pro. You can find more information at: shopping-cart-service-list.html VeriSign, Inc /Rev. 3 11

24 VeriSign Payment Services Payflow Pro Developer s Guide Supported Platforms Payflow Pro is available on all major Web server platforms in a variety of formats to support your integration requirements. It is available as a C library (.dll/.so), binary executable, Java library, COM object, Java Native Interface, and Perl Module Interface. Table 2-1 Payflow Pro supported platforms AIX 4.3 RedHat Linux 7.x, 8.x, 9.x BSDI 4.0 FreeBSD 4.x HP-UX 11.0 Solaris 2.6/Intel Solaris 2.6/Sparc Win32 Java 1.2, 1.3, 1.4 Preparing the Payflow Pro Client Application Follow these steps to download and install the Payflow Pro application. Step 1 Download the Payflow Pro SDK From the Download section of the VeriSign Manager ( download the Payflow Pro SDK appropriate for your platform. Step 2 Extract the files to a local directory Step 3 Configure your firewall Enable inbound traffic for SSL (port 443). Step 4 Set the certificate path To enable the client to authenticate the VeriSign Payment Services server, you must set the path to include the certs directory (included with the SDK that you downloaded). For specific information on setting the certificate path, see the Readme file and example applications in the SDK. Step 5 Read the Readme file The readme.txt file includes integration information and samples that illustrate how to use the client in your development environment. 12 VeriSign, Inc /Rev. 3

25 rte Chap CHAPTER 3 3Performing Credit Card Transactions This chapter describes the process of performing credit card transactions. Responses to transaction requests are described in Chapter 4, Responses to Credit Card Transaction Requests. Using Payflow Pro to define and manage recurring transactions is fully described in VeriSign Payflow Recurring Billing Service Guide for Payflow Pro. Note For information on TeleCheck transactions, skip this chapter and see Appendix B, Performing TeleCheck Electronic Check Transactions. In This Chapter + About Credit Card Processing on page Credit Card Transaction Format on page Parameters Used in Credit Card Transactions on page Values Required by All Transaction Types on page Submitting Sale Transactions on page Submitting Credit Transactions on page Submitting Void Transactions on page Submitting Voice Authorization Transactions on page Submitting Inquiry Transactions on page Submitting Authorization/Delayed Capture Transactions on page Submitting Purchasing Card Transactions on page Submitting Reference Transactions on page Using Address Verification Service (AVS) on page 38. VeriSign, Inc /Rev. 3 13

26 VeriSign Payment Services Payflow Pro Developer s Guide + Card Security Code (CSC) Validation on page Submitting Card-Present (Swipe) Transactions on page Logging Transaction Information on page 43. About Credit Card Processing Credit card processing occurs in two steps a real-time Authorization and a capture (settlement) of the funds that were authorized. As discussed below, you perform these two steps either as a single transaction or as two transactions, depending on your business model. For an Authorization, VeriSign sends the transaction information to a credit card processor who routes the transaction through the financial networks to the cardholder s issuing bank. The issuing bank checks whether the card is valid, evaluates whether sufficient credit exists, checks values such as Address Verification Service and Card Security Codes (discussed below), and returns a response: Approval, Decline, Referral, or others. You receive the response a few seconds after you submit the transaction to VeriSign. If the Authorization is approved, the bank temporarily reserves credit for the amount of the transaction to prepare to capture (fulfill) the transaction. The hold on funds typically lasts for about a week. Note You cannot remove a hold on funds through the processing networks you must contact the issuing bank to lift a hold early. Capturing a transaction (also known as settling a transaction) actually transfers the funds to your bank. At least once a day, VeriSign gathers all transactions that are flagged to be settled 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 actually available in your account, depending on your bank. Obtaining an Internet Merchant Account To accept credit cards over the Internet, you need a special account called an Internet Merchant Account. Your account provider or acquiring bank works with a VeriSign-supported credit card processor, such as First Data, Vital, or Paymentech. To use Payflow Pro to accept live credit cards, you must provide certain details about your account to VeriSign during the Go Live part of the enrollment process. 14 VeriSign, Inc /Rev. 3

27 Chapter 3 Performing Credit Card Transactions Note An Internet Merchant Account is separate from a merchant account used for in-person retail transactions due to the different risk profile for card-not-present (e-commerce) transactions. VeriSign has partnered with several Internet Merchant Account providers to make applying easy. Contact your VeriSign representative for more information. Planning Your Payflow Pro Integration In designing your Payflow Pro integration, you should evaluate the following: + 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. These transaction types are described in this chapter.) According to card association rules, most physical goods merchants should use a two-step process, since settlement should occur when the goods are fulfilled or shipped. A two-step process is also useful if you want to evaluate 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 (AVS) and card security code (CSC). For AVS, if the data is submitted with the initial transaction, the issuer checks the street address and/or the ZIP (postal) code against the billing address on file for the consumer. AVS is described on page 38. CSC refers to a 3- or 4-digit number that appears on the back of most credit cards. On American Express, the number appears above and to the right of the embossed card number. CSC is known by other names, such as CVV2 and CID, depending on the type of card. If CSC data is submitted, the issuer can notify you VeriSign, Inc /Rev. 3 15

28 VeriSign Payment Services Payflow Pro Developer s Guide whether the number matches the number assigned to the card. CSC is described on page 40. It may also be possible to implement additional safeguards yourself or to use a fraud service from VeriSign. You might want to discuss risk management with your Internet Merchant Account provider. + Store information in your local database or use VeriSign 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 VeriSign with the transaction and report on it later. Note VeriSign recommends that you do not store credit card numbers. If you must store numbers, encrypt and store them behind properly configured firewalls. You should also consider whether and how to use the merchant-defined fields COMMENT1 and COMMENT2 to help tie VeriSign 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 wish to connect these systems directly to Payflow Pro for capturing funds, issuing refunds/credits, and so on. Alternatively, you may prefer to perform these steps manually using VeriSign Manager. Either way, VeriSign recommends that you monitor transaction activity using VeriSign Manager. + You may want to discuss, with your Internet Merchant Acquirer, practices that help you to obtain the most advantageous rates. E-commerce Indicator (ECI) Some processors support a software flag called E-commerce Indicator (ECI) that indicates that the associated transaction is an Internet transaction. Payflow Pro complies with ECI basic requirements for all supported processors. If you use VeriSign s Buyer Authentication Service, then the ECI values reflects the Authentication status. See VeriSign User s Guide for Payflow Pro with Fraud Protection Services. 16 VeriSign, Inc /Rev. 3

29 Chapter 3 Performing Credit Card Transactions Credit Card Transaction Format Note The examples in this chapter use the syntax of the pfpro executable client. Other Payflow Pro clients differ in where and how the parameter values are set, but the meaning and uses are the same. Use the following syntax when calling the Payflow Pro client (pfpro) to process a transaction. Table 3-1 describes the arguments to the command. pfpro <HostAddress> <HostPort> <ParmList> <TimeOut> <ProxyAddress> <ProxyPort> <ProxyLogon> <ProxyPassword> For example: pfpro test-payflow.verisign.com 443 TRXTYPE=S&TENDER=C&PARTNER=VeriSign&VENDOR=SuperMerchant&U SER=SuperMerchant&PWD=x1y2z3&ACCT= &EXPDATE=03 08&AMT= Table 3-1 Arguments to the pfpro executable client Argument Required Description HOSTADDRESS Yes VeriSign s host name. For live transactions, use payflow.verisign.com For testing purposes use test-payflow.verisign.com HOSTPORT Yes Use port 443 PARMLIST Yes The ParmList is the list of parameters that specify the payment information for the transaction. The quotation marks at the beginning and end are required. In the example, the ParmList is: TRXTYPE=S&TENDER=C&PARTNER=VeriSign&VENDOR =SuperMerchant&USER=SuperMerchant&PWD=x1y2z3&A CCT= &EXPDATE=0308&AMT= The content of the ParmList varies by the type of transaction being processed. For example, a Void transaction requires a different set of parameters than does a Sale transaction. Parameters Used in Credit Card Transactions on page 19 defines the parameters used to create credit card transactions. Values Required by All Transaction Types on page 26 lists the parameters required by each transaction type. VeriSign, Inc /Rev. 3 17

30 VeriSign Payment Services Payflow Pro Developer s Guide Table 3-1 Arguments to the pfpro executable client (Continued) Argument Required Description TIMEOUT Yes Time-out period for the transaction. The minimum recommended time-out value is 30 seconds. The VeriSign client begins tracking from the time that it sends the transaction request to the VeriSign server. PROXYADDRESS No Proxy server address. Use the PROXY parameters for servers behind a firewall. Your network administrator can provide the values. PROXYPORT No Proxy server port PROXYLOGON No Proxy server logon ID PROXYPASSWORD No Proxy server logon password Command Syntax Guidelines Follow these guidelines: + The command must be a single string with no line breaks. + Spaces are allowed in values + Enclose the ParmList in quotation marks ( ). + Quotation marks ( ) are not allowed within the body of the ParmList. + Separate all name/value pairs in the ParmList using an ampersand (&). + Payflow Pro supports UTF-8 format for values passed in name/value pairs. + Calling pfpro without the required parameters results in an error message. Using Special Characters in Values Because the ampersand (&) and equal sign (=) characters have special meanings in the ParmList, name/value pairs like the following examples are not valid: NAME=Ruff & Johnson COMMENT1=Level=5 To use special characters in the value 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 name/value pairs are valid: NAME[14]=Ruff & Johnson COMMENT1[7]=Level=5 18 VeriSign, Inc /Rev. 3

31 Chapter 3 Performing Credit Card Transactions Note Quotation marks ( ) are not allowed even if you use a length tag. Parameters Used in Credit Card Transactions All credit card processors accept the parameters listed in Table 3-2 (required and optional parameters are noted). Values Required by All Transaction Types on page 26 lists the parameters required for each transaction type. Note Some processors require yet additional parameters. See Appendix A, Processors Requiring Additional Transaction Parameters, for details on your processor s requirements. Appendix E, Additional Reporting Parameters, provides a list of parameters that you can pass for reporting purposes. Table 3-2 Credit-card transaction parameters Parameter Description Required Type Max. Length ACCT AMT The credit card or purchase card number may not contain spaces, non-numeric characters, or dashes. For example, ACCT= Amount (US Dollars) U.S. based currency. Specify the exact amount to the cent using a decimal point use 34.00, not 34. Do not include comma separators use not 1, Your processor and/or Internet merchant account provider may stipulate a maximum amount. Yes 1 Numeric 19 Yes 1 Numeric USD only 10 AUTHCODE AUTHCODE is returned only for approved Voice Authorization transactions. AUTHCODE is the approval code obtained over the phone from the processing network. req d for Voice Authoriza tion only. Alphanumeric 6 COMMENT1 Merchant-defined value for reporting and auditing purposes. No Alphanumeric 128 COMMENT2 Merchant-defined value for reporting and auditing purposes. No Alphanumeric 128 VeriSign, Inc /Rev. 3 19

32 VeriSign Payment Services Payflow Pro Developer s Guide Table 3-2 Credit-card transaction parameters (Continued) Parameter Description Required Type Max. Length CUSTREF Merchant-defined identifier for reporting and auditing purposes. For example, you can set CUSTREF to the invoice number. No Alphanumeric 12 You can use CUSTREF when performing Inquiry transactions. To ensure that you can always access the correct transaction when performing an Inquiry, you must provide a unique CUSTREF when submitting any transaction, including retries. See STARTTIME and ENDTIME. CVV2 A 3- or 4-digit code that is printed (not imprinted) on the back of a credit card. Used as partial assurance that the card is in the buyer s possession. No Alphanumeric 4 See Card Security Code (CSC) Validation on page 40. ENDTIME EXPDATE 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. See STARTTIME. ENDTIME must be less than 30 days after STARTTIME. An inquiry cannot be performed across a date range greater than 30 days. If you set ENDTIME, and not STARTTIME, then STARTTIME is defaulted to 30 days before ENDTIME. If neither STARTTIME nor ENDTIME is specified, then the system searches the last 30 days. Format: yyyymmddhhmmss Expiration date of the credit card in mmyy format. For example, 0308 represents March No Numeric 14 Yes 1 Numeric 4 NAME or FIRSTNAME Account holder's name. This single field holds all of the person s name information. No, but recommended Alphanumeric upperca se VeriSign, Inc /Rev. 3

33 Chapter 3 Performing Credit Card Transactions Table 3-2 Credit-card transaction parameters (Continued) Parameter Description Required Type Max. Length ORIGID Yes 1 12 The ID of the original transaction that is being referenced. This ID is returned by the PNREF parameter and appears as the Transaction ID in VeriSign Manager reports. ORIGID is case-sensitive. Alphanumeric PARTNER The authorized VeriSign Reseller that registered you for the Payflow Pro service provided you with a Partner ID. If you registered yourself, use VeriSign. Yes Alphanumeric 12 Case-sensitive. PWD Case-sensitive 6- to 32-character password that you defined while registering for the account. Yes Alphanumeric 32 STARTTIME Optional for Inquiry transactions when using CUSTREF to specify the transaction. STARTTIME specifies the beginning of the time period during which the transaction specified by the CUSTREF occurred. See ENDTIME. If you set STARTTIME, and not ENDTIME, then ENDTIME is defaulted to 30 days after STARTTIME. If neither STARTTIME nor ENDTIME is specified, then the system searches the last 30 days. Format: yyyymmddhhmmss No Numeric 14 STREET The cardholder s street address (number and street name). No Alphanumeric 30 The STREET address is verified by the AVS service (described in page 38.) VeriSign, Inc /Rev. 3 21

34 VeriSign Payment Services Payflow Pro Developer s Guide Table 3-2 Credit-card transaction parameters (Continued) Parameter Description Required Type Max. Length SWIPE Used to pass the Track 1 or Track 2 data (the 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 POS application can send Track 2 data instead. Required only for cardpresent transactions Alphanumeric 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 18. TENDER The tender type (method of payment). Use the value C for credit card transactions. Yes Alpha 1 TRXTYPE A single character indicating the type of transaction to perform: TRXTYPE=S indicates a Sale transaction, C: Credit, A: Authorization, D: Delayed Capture, V: Void, F: Voice Authorization, I: Inquiry. Yes Alpha 1 USER Your login name. The examples in this document use USER=SuperMerchant. Yes Alphanumeric 64 This value is case-sensitive. You created the login name while registering for your Payflow account. Currently, USER takes the same value as VENDOR. In a future release, each account will allow multiple users. The USER parameter will then specify the particular user. VENDOR Your login name. The examples in this document use VENDOR=SuperMerchant. Yes Alphanumeric 64 This value is case-sensitive. You created the login name while registering for your Payflow account. 22 VeriSign, Inc /Rev. 3

35 Chapter 3 Performing Credit Card Transactions Table 3-2 Credit-card transaction parameters (Continued) Parameter Description Required Type Max. Length VERBOSITY LOW or MEDIUM. LOW is the default setting normalized values. MEDIUM returns the processor s raw response values. See Viewing Processor-specific Transaction Results: Verbosity on page 23. No Alpha ZIP Account holder s 5- to 9-digit ZIP (postal) code. Do not use spaces, dashes, or non-numeric characters. The postal code is verified by the AVS service and IAVS services (described on page 38). The ZIP code is verified by the AVS service (described in page 38.) No Alpha 9 1. Some transaction types do not require this parameter. See Values Required by All Transaction Types on page 26. Viewing Processor-specific Transaction Results: Verbosity Transaction results (especially values for declines and error conditions) returned by each VeriSign-supported processor vary in detail level and in format. The Payflow Pro Verbosity parameter enables you to control the kind and level of information you want returned. By default, Verbosity is set to LOW. A LOW setting causes VeriSign to normalize the transaction result values. Normalizing the values limits them to a standardized set of values and simplifies the process of integrating Payflow Pro. By setting Verbosity to MEDIUM, you can view the processor s raw response values. This setting is more verbose than the LOW setting in that it returns more detailed, processor-specific information. Supported Verbosity Settings The following Verbosity settings are supported for VeriSign-supported processors. Contact your processor or bank for definitions of the returned values. See Processor Contact Information: Transaction Settlement on page 6. VeriSign, Inc /Rev. 3 23

36 VeriSign Payment Services Payflow Pro Developer s Guide Note If you use Nashville, TeleCheck, or Paymentech, then you must use a client version newer than 2.09 to take advantage of the MEDIUM Verbosity setting. + LOW: This is the default setting for VeriSign accounts. The following values are returned: {RESULT, PNREF, RESPMSG, AUTHCODE, AVSADDR, AVSZIP, CVV2MATCH, IAVS, CARDSECURE} + MEDIUM: All of the values returned for a LOW setting, plus the following values: Note For information on interpreting the responses returned by the processor for the MEDIUM Verbosity setting, contact your processor directly. Processor contact information appears in Supported Processing Platforms on page 4. Table 3-3 Verbosity settings Field Name Type Length Description HOSTCODE char 7 Response code returned by the processor. This value is not normalized by VeriSign. RESPTEXT char 17 Text corresponding to the response code returned by the processor. This text is not normalized by VeriSign. PROCAVS char 1 AVS (Address Verification Service) response from the processor PROCCVV2 char 1 CVV2 (buyer authentication) response from the processor PROCCARDSECURE char 1 VPAS/SPA response from the processor ADDLMSGS char Up to 1048 characters. Typically 50 characters. Additional error message that indicates that the merchant used a feature that is disabled 24 VeriSign, Inc /Rev. 3

37 Chapter 3 Performing Credit Card Transactions Table 3-3 Verbosity settings Field Name Type Length Description TRANSSTATE Integer 10 State of the transaction. The values are: 0 = General succeed state 1 = General error state 3 = Authorization approved 6 = Settlement pending (transaction is scheduled to be settled) 7 =Settlement in progress (transaction involved in a currently ongoing settlement) 8 = Settled successfully 9 = Authorization captured (once an authorization type transaction is captured, its TRANSSSTATE becomes 9) 10 =Capture failed (an error occurred while trying to capture an authorization because the transaction was already captured) 11 = Failed to settle (transactions fail settlement usually because of problems with the merchant s processor or because the card type is not set up with the merchant s processor) 12 - Unsettled transaction because of incorrect account information 14 = For various reasons, the batch containing this transaction failed settlement 16 = Merchant ACH settlement failed; (need to manually collect it) DATE_TO_SETTLE Date format YYYY-MM-DD HH:MM:SS 19 Value available only before settlement has started. BATCHID Integer 10 Value available only after settlement has assigned a Batch ID. VeriSign, Inc /Rev. 3 25

38 VeriSign Payment Services Payflow Pro Developer s Guide Table 3-3 Verbosity settings Field Name Type Length Description SETTLE_DATE Date format YYYY-MM-DD HH:MM:SS 19 Value available only after settlement has completed. Table 3-4 shows the increments that are possible on basic TRANSSTATE values. Table 3-4 TRANSSTATE increments Increment Meaning +100 No client acknowledgment (ACK)is received (=status 0 in V2), for example, 106 is TRANSSTATE The host process never receives ACK from the transaction broker (or backend payment server). A transaction with a TRANSSTATE of +200 is basically in limbo and will not be settled Voided transactions. Any TRANSSTATE of (for example, 1006) means the transaction was settle pending. However, it was voided either through the API, VeriSign Manager, or VeriSign Customer Service. Changing the Verbosity Setting Setting the default Verbosity level for all transactions Contact VeriSign Customer Service to set your account s Verbosity setting to LOW or MEDIUM for all transaction requests. Setting the Verbosity level on a per-transaction basis To specify a setting for Verbosity that differs from your account s current setting, include the VERBOSITY=<value> name/value pair in the transaction request, where <value> is LOW or MEDIUM. Values Required by All Transaction Types All transaction APIs require values for the TRXTYPE, TENDER, PARTNER, VENDOR, USER, and PWD parameters. Each transaction API has additional parameter requirements, as listed here. Transaction responses are described in Chapter 4, Responses to Credit Card Transaction Requests. 26 VeriSign, Inc /Rev. 3

39 Chapter 3 Performing Credit Card Transactions Submitting Sale Transactions The Sale transaction (TRXTYPE=S) charges the specified amount against the account, and marks the transaction for immediate fund transfer during the next settlement period. VeriSign submits each merchant s transactions for settlement on a daily basis. Additional Required Parameters for Sale Transactions The set: [ACCT, EXPDATE, and AMT] or Set ORIGID to the PNREF (Transaction ID in VeriSign Manager reports) value returned for the original transaction. When you use ORIGID, the Sale transaction uses the transaction referred to by the ORIGID as a reference transaction. See Submitting Reference Transactions on page 35. Example Sale Transaction Parameter List TRXTYPE=S&TENDER=C&PARTNER=VeriSign&VENDOR=SuperMerchant&USER =SuperMerchant&PWD=x1y2z3&ACCT= &EXPDATE=0308&AMT = Submitting Credit Transactions The Credit transaction (TRXTYPE=C) refunds the specified amount to the cardholder. Additional Required Parameters for Credit Transactions The required data for a Credit transaction depends on the Allow non-referenced credits security setting for your Payflow account, as follows: + If non-referenced credits are not allowed (the setting recommended by VeriSign), then Credit transactions are permitted only against existing Sale, Delayed Capture, and Void transactions. To submit a Credit transaction, you must set ORIGID to the PNREF value returned for the original transaction (PNREF is displayed as the Transaction ID in VeriSign Manager reports). If you do not specify an amount, then the amount of the original transaction is credited to the cardholder. Note For Test servers, the first and fourth characters in the PNREF value are alpha characters (letters), and the second and third characters are numeric VeriSign, Inc /Rev. 3 27

40 VeriSign Payment Services Payflow Pro Developer s Guide (Example: V53A ). For Live servers, all of the first four characters are alpha characters, for example: VPNE If non-referenced credits are allowed, then Credit transactions are permitted in any amount up to the transaction limit for the credit card account that you specify. You must send values for ACCT, EXPDATE, and AMT. IMPORTANT! The default security setting for Payflow accounts is Allow non-referenced credits = No, so sending the ORIGID is the preferred method for performing Credit transactions. Using the ACCT, EXPDATE, or AMT parameters for such accounts leads to Result code 117 (failed the security check). For information on setting the security settings, see the chapter on configuring account security in VeriSign Manager User s Guide. 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, then the new value is used (except Account number, Expiration date, or Swipe data). Note These fields are not copied for referenced credits: Tax amount, Tax exempt, Duty amount, Freight amount, and (for amex only) desc4. Note For processors that use the RECURRING parameter: If the RECURRING parameter was set to Y for the original transaction, then the setting is ignored when forming the Credit transaction. Account number Amount City Comment1 Comment2 Company Name Country Cust_Code CustIP DL Num DOB Expiration date First name Invoice number Last name Middle Name Purchase order number Ship To City Ship To Country 28 VeriSign, Inc /Rev. 3

41 Chapter 3 Performing Credit Card Transactions Ship To First Name Ship To Last Name Ship To Middle Name Ship To State Ship To Street Ship To ZIP SS Num State Street Suffix Swipe data Telephone Title ZIP Example Credit Transaction Parameter List TRXTYPE=C&TENDER=C&PARTNER=VeriSign&VENDOR=SuperMerchant&USER =SuperMerchant&PWD=x1y2z3&ORIGID=VPNE or TRXTYPE=C&TENDER=C&PARTNER=VeriSign&VENDOR=SuperMerchant&USER =SuperMerchant&PWD=x1y2z3&ACCT= &EXPDATE=0308&AMT = Submitting Void Transactions The Void transaction (TRXTYPE=V) prevents a transaction from being settled, but does not release the Authorization (hold on funds) on the cardholder s account. Follow these guidelines: + You can void Delayed Capture, Sale, Credit, Authorization, and Voice Authorization transactions. You cannot void a Void transaction. + Void transactions can only be used on transactions that have not yet settled. To refund the customer s money for settled transactions, you must submit a Credit transaction. Additional Required Parameters for Void Transactions Set ORIGID to the PNREF (Transaction ID in VeriSign Manager reports) value returned for the original transaction. 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, then the new value is used (except Account number, Expiration date, or Swipe data). VeriSign, Inc /Rev. 3 29

42 VeriSign Payment Services Payflow Pro Developer s Guide Note For processors that use the RECURRING parameter: If the RECURRING parameter was set to Y for the original transaction, then the setting is ignored when forming the Void transaction. Account number Amount City Comment1 Comment2 Company Name Country Cust_Code CustIP DL Num DOB Duty amount Expiration date First name Freight amount Invoice number Last name Middle Name Purchase order number Ship To City Ship To Country Ship To First Name Ship To Last Name Ship To Middle Name Ship To State Ship To Street Ship To ZIP SS Num State Street Suffix Swipe data Tax amount Tax exempt Telephone Title ZIP Example Void Transaction Parameter List TRXTYPE=V&TENDER=C&PARTNER=VeriSign&VENDOR=SuperMerchant&USER =SuperMerchant&PWD=x1y2z3&ORIGID=VPNE Submitting Voice Authorization Transactions Some transactions cannot be authorized over the Internet (for example, high dollar amounts) processing networks generate Referral (Result Code 13) transactions for such requests. In these situations, you contact the customer service department of your merchant bank and provide the payment information as requested. If the transaction is approved, the bank provides you with a voice Authorization code (AUTHCODE) for the transaction. You include this AUTHCODE as part of a Voice Authorization (TRXTYPE=F) transaction. Once a Voice Authorization transaction has been approved, it is treated like a Sale transaction and is settled with no further action on your part. Like Sale transactions, approved Voice Authorization transactions can be voided. 30 VeriSign, Inc /Rev. 3

43 Chapter 3 Performing Credit Card Transactions Additional Required Parameters for Voice Authorization Transactions AUTHCODE ACCT EXPDATE AMT Example Voice Authorization Transaction Parameter List TRXTYPE=F&TENDER=C&PARTNER=VeriSign&VENDOR=SuperMerchant&USER =SuperMerchant&PWD=x1y2z3&AUTHCODE=AB34RT56&ACCT= &EXPDATE=0308&AMT= Submitting Inquiry Transactions An Inquiry transaction (TRXTYPE=I) returns the result and status of a transaction. You perform inquiries using a reference to the original transaction either the PNREF value returned for the original transaction or the CUSTREF value that you specified for the original transaction. Inquiries based on a CUSTREF value return data on the most recent non-inquiry transaction rather than the first transaction. 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 much as possible. Using the PNREF to Perform Inquiry Transactions Set ORIGID to the PNREF (Transaction ID in VeriSign Manager reports) value returned for the original transaction. Example Inquiry Transaction Parameter List, Using the ORIGID Parameter set to the PNREF Value TRXTYPE=I&TENDER=C&PARTNER=VeriSign&VENDOR=SuperMerchant&USER =SuperMerchant&PWD=x1y2z3&ORIGID=VPNE Using the CUSTREF to Perform Inquiry Transactions Specify the CUSTREF value and, optionally, the STARTTIME and ENDTIME parameters. VeriSign, Inc /Rev. 3 31

44 VeriSign Payment Services Payflow Pro Developer s Guide CAUTION If there are multiple transactions with a particular CUSTREF value, then the Inquiry transaction returns only the first transaction with the specified CUSTREF. So, to ensure that you can always access the correct transaction, you must use a unique CUSTREF when submitting any transaction, including retries. Example Inquiry Transaction Parameter List, Using the CUSTREF TRXTYPE=I&TENDER=C&PARTNER=VeriSign&VENDOR=SuperMerchant&USER =SuperMerchant&PWD=x1y2z3&CUSTREF=Inv Submitting Authorization/Delayed Capture Transactions Visa/MasterCard regulations prohibit merchants from capturing credit card transaction funds until product has shipped to the buyer. Because of this rule, most processing networks implement a two-stage transaction solution. VeriSign refers to this as Delayed Capture processing. This process consists of an Authorization (TRXTYPE=A) transaction followed (when the merchant is ready to collect funds) by a Delayed Capture (TRXTYPE=D) transaction. An Authorization transaction does not transfer funds, rather it places a hold on the cardholder s open-to-buy limit, lowering the cardholder s limit by the amount of the transaction. A Delayed Capture transaction then captures the original Authorization amount. The transaction is scheduled for settlement during the next settlement period. IMPORTANT! Only one Delayed Capture transaction is allowed per Authorization transaction. Additional Required Parameters for Authorization Transactions The set: [ACCT, EXPDATE, and AMT] or Perform a reference transaction by specifying the ORIGID of an existing transaction. See Submitting Reference Transactions on page 35. Additional Required Parameters for Delayed Capture Transactions Set ORIGID to the PNREF (Transaction ID in VeriSign Manager reports) value returned for the original transaction. If the amount of the capture differs from the amount of the Authorization, then you must specify a value for AMT. 32 VeriSign, Inc /Rev. 3

45 Chapter 3 Performing Credit Card Transactions Fields Copied From the Authorization Transaction into the Delayed Capture Transaction The following fields are copied from the Authorization transaction into the Delayed Capture transaction (if they exist in the original transaction). If you provide a new value for any of these parameters when submitting the Delayed Capture transaction, then the new value is used (except Account number, Expiration date, or Swipe data). Account number Amount City Comment1 Comment2 Company Name Country Cust_Code CustIP DL Num DOB Duty amount Expiration date First name Freight amount Invoice number Last name Middle Name Purchase order number Ship To City Ship To Country Ship To First Name Ship To Last Name Ship To Middle Name Ship To State Ship To Street Ship To ZIP SS Num State Street Suffix Swipe data Tax amount Tax exempt Telephone Title ZIP Step 1 Perform the Authorization transaction The Authorization transaction uses the same parameters as Sale transactions, except that the transaction type is A. The return data for an Authorization transaction is the same as for a Sale transaction. To capture the authorized funds, perform a Delayed Capture transaction that includes the value returned for PNREF, as described in Step 2 on page 34. IMPORTANT! For Test servers, the first and fourth characters in the PNREF value are alpha characters (letters), and the second and third characters are numeric (Example: V53A ). For Live servers, all of the first four characters are alpha characters (letters), for example: VPNE VeriSign, Inc /Rev. 3 33

46 VeriSign Payment Services Payflow Pro Developer s Guide Example Authorization Transaction Parameter List Issue Authorization-only Transaction TRXTYPE=A&TENDER=C&PWD=x1y2z3&PARTNER=VeriSign &VENDOR=SuperMerchant&USER=SuperMerchant&ACCT= &EX PDATE=0308&AMT=123.00&COMMENT1=Second purchase &COMMENT2=Low risk customer&invnum= &street=5199 MAPLE&ZIP=94588 Example Authorization Response RESULT=0&PNREF=VXYZ &RESPMSG=APPROVED&AUTHCODE= &AVSADDR=Y&AVSZIP=N Step 2 Perform the Delayed Capture transaction Set ORIGID to the PNREF value from the original Authorization transaction. (There is no need to retransmit the credit card or billing address information it is stored at VeriSign.) If the capture succeeds, the amount of the Sale is transferred to the merchant s account during the daily settlement process. If the capture does not succeed, the hold on the cardholder s open-to-buy is still in effect. Example Delayed Capture Transaction Parameter List TRXTYPE=D&TENDER=C&PWD=x1y2z3&PARTNER=VeriSign&VENDOR=SuperMe rchant&user=supermerchant&origid=vxyz Example Delayed Capture Response RESULT=0&PNREF=VXYZ &AUTHCODE=25TEST&AVSADDR=Y&AVSZIP =N Delayed Capture Transaction: Capturing Transactions for Lower Amounts You can perform a Delayed Capture transaction for an amount lower than the original Authorization amount (useful, for example, when you make a partial shipment). Delayed Capture Transaction: Capturing Transactions for Higher Amounts You can perform a Delayed Capture transaction for an amount higher than the original Authorization amount, however, you are charged for an extra transaction. In addition, the cardholder s open-to-buy is reduced by the sum of the original Authorization-only amount and the final Delayed Capture amount. 34 VeriSign, Inc /Rev. 3

47 Chapter 3 Performing Credit Card Transactions Delayed Capture Transaction: Error Handling and Retransmittal If an error occurs while processing a Delayed Capture transaction, it is safe to retry the capture with values that allow the VeriSign server to successfully process it. Conversely, if a capture for a previous Authorization succeeds, subsequent attempts to capture it again will return an error. 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 is issued at the request of an employer. It 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, you must pass specific additional transaction information. Commercial card support and parameters vary from processor to processor. See Appendix D, Submitting Purchasing Card Level 2 and Level 3 Transactions. Submitting Reference Transactions CAUTION 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 for which reference transactions are disallowed, result code 117 is returned. See VeriSign Manager User s Guide for instructions on setting this and other VeriSign Manager security features. Sale and Authorization transactions can make use of a reference transaction as a source of transaction data. VeriSign looks up the reference transaction and copies its transaction data into the new Sale or Authorization transaction. VeriSign, Inc /Rev. 3 35

48 VeriSign Payment Services Payflow Pro Developer s Guide IMPORTANT! When VeriSign looks up the reference transaction, neither the transaction being referenced nor any other transaction in the database is changed in any way. That is, a reference transaction is a read-only operation only the new transaction is populated with data and acted upon. No linkage is maintained between the reference transaction and the new transaction. Reference transactions are not screened by Fraud Protection Services filters. You can also initiate reference transactions from VeriSign Manager. See VeriSign Manager User s Guide for details. Transaction Types that can be Used as the Original Transaction You can reference the following transaction types to supply data for new Sale or Authorization transactions: Authorization (To capture the funds for an approved Authorization transaction, be sure to perform a Delayed Capture transaction not a Reference transaction.) Credit Delayed Capture Sale Voice Authorization (The Voice Authorization code is not copied to the new transaction) Void Fields Copied From Reference Transactions The following fields are copied from the referenced 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. 36 VeriSign, Inc /Rev. 3

49 Chapter 3 Performing Credit Card Transactions Fields Copied From Original Transactions Account Type Account Number Expiration Date First Name Middle Name Last Name Street City State ZIP Country Swipe Data 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 transaction. 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. Step 1 Submit the Initial transaction (Authorization in this example) You use an Authorization transaction for the full amount of the purchase of $100: "TRXTYPE=A&TENDER=C&PWD=x1y2z3&PARTNER=VeriSign&VENDOR=SuperMerc hant&user=supermerchant&acct= &expdate=0308&amt= &INVNUM= &STREET=5199 MAPLE&ZIP=94588" RESULT=0&PNREF=VXYZ &RESPMSG=APPROVED&AUTHCODE=123456& AVSADDR=Y&AVSZIP=N Step 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. "TRXTYPE=D&TENDER=C&PWD=x1y2z3&PARTNER=VeriSign&VENDOR=SuperMerc hant&user=supermerchant&origid=vxyz &amt=66.00" RESULT=0&PNREF=VXYZ &AUTHCODE=25TEST&AVSADDR=Y&AVSZIP= N Step 3 Submit a new Sale transaction of $34 for the rest of the shipment Once you have shipped 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 only one Delayed Capture transaction is allowed per Authorization.) VeriSign, Inc /Rev. 3 37

50 VeriSign Payment Services Payflow Pro Developer s Guide "TRXTYPE=S&TENDER=C&PWD=x1y2z3&PARTNER=VeriSign&VENDOR=SuperMerc hant&user=supermerchant&origid=vxyz &amt=34.00" RESULT=0&PNREF=VXYZ &AUTHCODE=25TEST&AVSADDR=Y&AVSZIP= N Note In the case that your business model uses the Authorization/Delayed Capture cycle for all transactions, you could have chosen to use an Authorization/Delayed Capture to collect the $34 in this example. You would generate the Authorization for the $34 using the initial Authorization as a reference transaction. Using Address Verification Service (AVS) To qualify for the lowest bank rate, you must pass Address Verification Service (AVS) information street address and ZIP (postal) code. AVS compares the submitted street address and ZIP code with the values on file at the cardholder s bank. The response includes values for AVSADDR and AVSZIP: Y, N, or X for the match status of the customer s street address and ZIP code. Y =match, N =nomatch, X = cardholder s bank does not support AVS. The AVS result is for advice only. Banks do not decline transactions based on the AVS result the merchant makes the decision to approve or decline a transaction. AVS is supported by most US banks and some international banks. Note AVS 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 AVS response (IAVS) indicates whether AVS response is international (Y), USA (N), or cannot be determined (X). Client version 3.06 or later is required. Processing Platforms Supporting AVS VeriSign supports the AVS services as listed in Table 3-5. Table 3-5 Processing platforms supporting AVS Processing Platform American Express Discover MasterCard Visa American Express Phoenix American Express APAC 38 VeriSign, Inc /Rev. 3

51 Chapter 3 Performing Credit Card Transactions Table 3-5 Processing platforms supporting AVS Processing Platform American Express Discover MasterCard Visa FDMS Nashville FDMS North FDMS South Global Payments Central Global Payments East Norwest Nova Paymentech New Hampshire Vital Wells Fargo Bank Tip See your processor s information in Appendix A, Processors Requiring Additional Transaction Parameters, for information on their handling of AVS. Example AVS Request Parameter List This example request include the AVS request parameters STREET and ZIP: TRXTYPE=A&TENDER=C&PWD=x1y2z3&PARTNER=VeriSign&VENDOR=SuperMe rchant&user=supermerchant&&acct= &expdate=0308&amt =123.00&STREET=5199 Maple&ZIP=98765 Example AVS Response In this example, the address value matches the value in the bank s records, but the ZIP code does not. The IAVS response is X. RESULT=0&PNREF=VXW &RESPMSG=APPROVED&AUTHCODE= &AVSADDR=Y&AVSZIP=N&IAVS=X VeriSign, Inc /Rev. 3 39

52 VeriSign Payment Services Payflow Pro Developer s Guide Card Security Code (CSC) Validation The card security code (CSC) is a 3- or 4-digit number (not part of the credit card number) that is printed on the credit card. Because the CSC appears only on the card and not on receipts or statements, the CSC provides some assurance that the physical card is in the possession of the buyer. Tip This fraud prevention tool has various names, depending on the payment network. Visa calls it CVV2, MasterCard calls it CVC2, and American Express and Discover call it CID. To ensure that your customers see a consistent name, VeriSign recommends use of the term Card Security Code (CSC) on all end-user materials. On most cards, the CSC is printed on the back of the card (usually in the signature field). All or part of the card number appears before the CSC (567 in the example). For American Express, the 4-digit number (1122 in the example) is printed on the front of the card, above and to the right of the embossed account number. Be sure to explain this to your customers. Processing Platforms and Credit Cards Supporting CSC VeriSign supports the CSC validation services as listed in Table 3-6. Table 3-6 Processing platforms and credit cards supporting CSC Processing Platform American Express Discover MasterCard Visa American Express Phoenix American Express APAC FDMS Nashville FDMS North FDMS South 40 VeriSign, Inc /Rev. 3

53 Chapter 3 Performing Credit Card Transactions Table 3-6 Processing platforms and credit cards supporting CSC Processing Platform American Express Discover MasterCard Visa Global Payments Central Global Payments East Norwest Nova Paymentech New Hampshire Vital Even though your processor may be certified for CSC, they may not be certified for all card types (for example, American Express (CID), or Discover). The list will change as VeriSign continues to enhance its service offering. See for the latest information. Special Case: American Express To enable the account to accept the CSC code, you must send an request to [email protected]. Once American Express has approved the request and has activated CSC for the you, you can begin passing CSC data and receiving the appropriate responses (Y, N, or X). If you attempt to send CSC data without having requested setup, American Express does not send a response. CSC Results If you submit the CVV2 parameter, the cardholder s bank returns a Yes/No response in the CVV2MATCH response value as follows: Table 3-7 CVV2MATCH response values CVV2MATCH Value Y N X Description The submitted value matches the data on file for the card. The submitted value does not match the data on file for the card. The cardholder s bank does not support this service. VeriSign, Inc /Rev. 3 41

54 VeriSign Payment Services Payflow Pro Developer s Guide CSC results vary depending on your processing platform, as described in Table 3-8: Table 3-8 CSC results Processing Platform American Express Phoenix American Express APAC Vital Nova Global Payments East Global Payments Central FDMS Nashville FDMS South Paymentech New Hampshire Results CSC mismatches cause a non-approved result (RESULT = 114). No CVV2MATCH value is returned. CSC mismatches may cause a non-approved result (RESULT = 112 or 114) in some cases. In other cases, the transaction may be approved despite the CSC mismatch. The match or mismatch information is indicated in the CVV2MATCH value. Transactions that have CSC mismatches can come back as an approved transaction (RESULT = 0). The match or mismatch information is indicated in the CVV2MATCH value. As with AVS, if the Authorization was successful, you must make a decision based on the CVV2MATCH value whether or not to proceed with the order. Example CVV2 Request This example request includes the CVV2 parameter: TRXTYPE=A&TENDER=C&PWD=x1y2z3&PARTNER=VeriSign&VENDOR=SuperMe rchant&user=supermerchant&&acct= &expdate=0308&amt =123.00&CVV2=567 Example CVV2MATCH Response In this example result, the CSC value matches the value in the bank s records. RESULT=0&PNREF=VXW &RESPMSG=APPROVED&AUTHCODE= &CVV2MATCH=Y Submitting Card-Present (Swipe) Transactions Payflow Pro supports card-present transactions (face-to-face purchases). Follow these guidelines to take advantage of the lower card-present transaction rate: + Contact your merchant account provider to ensure that they support card-present transactions. 42 VeriSign, Inc /Rev. 3

55 Chapter 3 Performing Credit Card Transactions + Contact VeriSign to set up a separate Payflow Pro account for card-present transactions. Supported Processing Platforms VeriSign is certified to submit card-present transactions for the following processing platforms: American Express Phoenix American Express APAC First Data Merchant Services (FDMS) Nashville First Data Merchant Services (FDMS) North First Data Merchant Services (FDMS) South Nova Paymentech New Hampshire Vital 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 not both (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 must count the characters in the track data and pass that number. Length tags are described in Using Special Characters in Values on page 18. The length tag in the following example is [40]. Do not include the ACCT or EXPDATE parameters in card-present transactions. Example Card-present Transaction Parameter List TRXTYPE=S&TENDER=C&PARTNER=VeriSign&USER=SuperMerchant&PW D=SuperMerchant&SWIPE[40]=; = ?&AMT=21.00 Logging Transaction Information VeriSign maintains a record of all transactions executed on your account. This record is not the official bank statement. The credit card transaction summary that you receive from your acquiring bank is the official record. VeriSign, Inc /Rev. 3 43

56 VeriSign Payment Services Payflow Pro Developer s Guide Use VeriSign Manager at to view this record and use the information to help reconcile your accounting records. VeriSign strongly recommends that you log all transaction results on your own system and that you do not store credit card information. At a minimum, log the following data: + PNREF IMPORTANT! For Test servers, the first and fourth characters in the PNREF value are alpha characters (letters), and the second and third characters are numeric (for example, V53A ). For Live servers, all of the first four characters are alpha characters (for example, VPNE ). + Transaction Date + Transaction Amount + AUTHCODE If you have any questions regarding a transaction, refer to or search on the PNREF. In VeriSign Manager reports, the PNREF value appears in the Transaction ID column. 44 VeriSign, Inc /Rev. 3

57 rte Chap CHAPTER 4 4Responses to Credit Card Transaction Requests This chapter describes the contents of a response to a credit card transaction request. When a transaction finishes, VeriSign returns a response string made up of name/value pairs. For example, this is a response to a credit card Sale transaction request: RESULT=0&PNREF=VXYZ &RESPMSG=APPROVED&AUTHCODE= &AVSADDR=Y&AVSZIP=N&IAVS=Y&CVV2MATCH=Y Contents of a Response to a Credit Card Transaction Request All transaction responses include values for RESULT, PNREF, RESPMSG. A value for AUTHCODE is included for Voice Authorization transactions. Values for AVSADDR and AVSZIP are included if you use AVS. Table 4-1 describes the values returned in a response string. Table 4-1 Transaction response values Field Description Type Length PNREF VeriSign Reference ID, a unique number that identifies the transaction. PNREF is described in PNREF Format on page 47. Alphanumeric 12 RESULT The outcome of the attempted transaction. A result of 0 (zero) indicates the transaction was approved. Any other number indicates a decline or error. RESULT codes are described in RESULT Codes and RESPMSG Values on page 47. Numeric Variable CVV2MATCH Result of the card security code (CVV2) check. This value does not affect the outcome of the transaction. Alpha Y, N, X, or no response 1 VeriSign, Inc /Rev DRAFT

58 VeriSign Payment Services Payflow Pro Developer s Guide Table 4-1 Transaction response values (Continued) Field Description Type Length RESPMSG The response message returned with the transaction result. Exact wording varies. Sometimes a colon appears after the initial RESPMSG followed by more detailed information. Response messages are described in RESULT Codes and RESPMSG Values on page 47. Alphanumeric Variable AUTHCODE Returned for Sale, Authorization, and Voice Authorization transactions. AUTHCODE is the approval code obtained over the phone from the processing network. Alphanumeric 6 AUTHCODE is required when submitting a Force (F) transaction. AVSADDR AVS address responses are for advice only. This process does not affect the outcome of the authorization. See Using Address Verification Service (AVS) on page 38. Alpha Y, N, X, or no response 1 AVSZIP AVS ZIP code responses are for advice only. This process does not affect the outcome of the authorization. See Using Address Verification Service (AVS) on page 38. Alpha Y, N, X, or no response 1 IAVS International AVS address responses are for advice only. This value does not affect the outcome of the transaction. Indicates whether AVS response is international (Y), US (N), or cannot be determined (X). Client version 3.06 or later is required. Alpha Y, N, X, or no response 1 See Using Address Verification Service (AVS) on page 38. PNREF Value The PNREF is a unique transaction identification number issued by VeriSign that identifies the transaction for billing, reporting, and transaction data purposes. The PNREF value appears in the Transaction ID column in VeriSign Manager reports. 46 VeriSign, Inc /Rev. 3 DRAFT

59 Chapter 4 Responses to Credit Card Transaction Requests The PNREF value is used as the TRANSID 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 TRANSID value (original transaction ID) value in reference transactions for authorization (TRXTYPE=A) and Sale (TRXTYPE=S). Note The PNREF is also referred to as the Transaction ID in Payflow Link documentation. PNREF Format The PNREF is a 12-character string of printable characters, for example: VADE0B ACRAF23DB3C4 Note Printable characters also include symbols other than letters and numbers such as the question mark (?). A PNREF typically contains letters and numbers only. Historically, the contents of a PNREF indicated a test or a live transaction: For Test servers, the first and fourth characters were alpha characters (letters), and the second and third characters were numeric, for example: V53A For Live servers, the first four characters were alpha characters (letters), for example: VPNE However, this is not always the case, and as a rule, you should not place any meaning on the contents of a PNREF. RESULT Codes and RESPMSG Values RESULT is the first value returned in the VeriSign server response string. The value of the RESULT parameter indicates the overall status of the transaction attempt. A value of 0 (zero) indicates that no errors occurred and the transaction was approved. DRAFT VeriSign, Inc /Rev. 3 47

60 VeriSign Payment Services Payflow Pro Developer s Guide A value less than zero indicates that a communication error occurred. In this case, no transaction is attempted. A value greater than zero indicates a decline or error. The response message (RESPMSG) provides a brief description for decline or error results. RESULT Values for Transaction Declines or Errors For non-zero Results, the response string includes a RESPMSG name/value pair. The exact wording of the RESPMSG (shown in bold) may vary. Sometimes a colon appears after the initial RESPMSG followed by more detailed information. Table 4-2 VeriSign transaction RESULT values and RESPMSG text RESULT RESPMSG and Explanation 0 Approved 1 User authentication failed. Error is caused by one or more of the following: Invalid User ID, Merchant Login ID, Partner ID, or Password entered in your parameter string. Login information is case-sensitive. Invalid Processor information entered. Contact merchant bank to verify. "Allowed IP Address" security feature implemented. Test account submitting transactions to live VeriSign servers. 2 Invalid tender type. Your merchant bank account does not support the following credit card type that was submitted. 3 Invalid transaction type. Transaction type is not appropriate for this transaction. For example, you cannot credit an authorization-only transaction. 4 Invalid amount format 5 Invalid merchant information. Processor does not recognize your merchant account information. Contact your bank account acquirer to resolve this problem. 7 Field format error. Invalid information entered. See RESPMSG. 8 Not a transaction server 9 Too many parameters or invalid stream 10 Too many line items 11 Client time-out waiting for response 48 VeriSign, Inc /Rev. 3 DRAFT

61 Chapter 4 Responses to Credit Card Transaction Requests Table 4-2 VeriSign transaction RESULT values and RESPMSG text RESULT RESPMSG and Explanation 12 Declined. Check the credit card number and transaction information to make sure they were entered correctly. If this does not resolve the problem, have the customer call the credit card issuer to resolve. 13 Referral. Transaction was declined but could be approved with a verbal authorization from the bank that issued the card. Submit a manual Voice Authorization transaction and enter the verbal auth code. 19 Original transaction ID not found. The transaction ID you entered for this transaction is not valid. See RESPMSG. 20 Cannot find the customer reference number 22 Invalid ABA number 23 Invalid account number. Check credit card number and re-submit. 24 Invalid expiration date. Check and re-submit. 25 Invalid Host Mapping. Not signed up for this tender type. 26 Invalid vendor account 27 Insufficient partner permissions 28 Insufficient user permissions 29 Invalid XML document. This could be caused by an unrecognized XML tag or a bad XML format that cannot be parsed by the system. 30 Duplicate transaction 31 Error in adding the recurring profile 32 Error in modifying the recurring profile 33 Error in canceling the recurring profile 34 Error in forcing the recurring profile 35 Error in reactivating the recurring profile 36 OLTP Transaction failed 37 Invalid recurring profile ID 50 Insufficient funds available in account 99 General error. See RESPMSG. DRAFT VeriSign, Inc /Rev. 3 49

62 VeriSign Payment Services Payflow Pro Developer s Guide Table 4-2 VeriSign transaction RESULT values and RESPMSG text RESULT RESPMSG and Explanation 100 Transaction type not supported by host 101 Time-out value too small 102 Processor not available 103 Error reading response from host 104 Timeout waiting for processor response. Try your transaction again. 105 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.) 106 Host not available 107 Duplicate suppression time-out 108 Void error. See 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). 109 Time-out waiting for host response 111 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. 112 Failed AVS check. Address and ZIP code do not match. An authorization may still exist on the cardholder s account. 113 Merchant sale total will exceed the sales cap with current transaction. ACH transactions only. 114 Card Security Code (CSC) Mismatch. An authorization may still exist on the cardholder s account. 115 System busy, try again later 116 VPS Internal error. Failed to lock terminal number 50 VeriSign, Inc /Rev. 3 DRAFT

63 Chapter 4 Responses to Credit Card Transaction Requests Table 4-2 VeriSign transaction RESULT values and RESPMSG text RESULT RESPMSG and Explanation 117 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 VeriSign Manager Security Settings page. If the transaction exceeded the Maximum Amount security setting, then no values are returned for AVS or CSC. See VeriSign Manager User s Guide for information on the Security Settings page. AVS validation failed. The AVS return value should appear in the RESPMSG. CSC validation failed. The CSC return value should appear in the RESPMSG. 118 Invalid keywords found in string fields 122 Merchant sale total will exceed the credit cap with current transaction. ACH transactions only. 125 Fraud Protection Services Filter Declined by filters 126 Fraud Protection Services Filter Flagged for review by filters Important Note: Result code 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. This result occurred due to that fact that all new Payflow accounts include a test drive of the Fraud Protection Services at no charge. The filters are on by default, and a suspicious transaction triggered Result code 126. You can modify these settings based on your business needs. Result code 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 chapter entitled Assessing Transactions that Triggered Filters in Fraud Protection Services Guide or User s Guide for Payflow Link Guide With Fraud Protection Services. 127 Fraud Protection Services Filter Not processed by filters 128 Fraud Protection Services Filter Declined by merchant after being flagged for review by filters 131 Version 1 Payflow Pro SDK client no longer supported. Upgrade to the most recent version of the Payflow Pro client. 150 Issuing bank timed out DRAFT VeriSign, Inc /Rev. 3 51

64 VeriSign Payment Services Payflow Pro Developer s Guide Table 4-2 VeriSign transaction RESULT values and RESPMSG text RESULT RESPMSG and Explanation 151 Issuing bank unavailable 1000 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 1002 Buyer Authentication Service Transaction timeout 1003 Buyer Authentication Service Invalid client version 1004 Buyer Authentication Service Invalid timeout value 1011 Buyer Authentication Service unavailable 1012 Buyer Authentication Service unavailable 1013 Buyer Authentication Service unavailable 1014 Buyer Authentication Service Merchant is not enrolled for Buyer Authentication Service (3-D Secure). To enroll, log in to VeriSign Manager, click Security, and then click the Buyer Authentication Service banner on the page 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 1022 Buyer Authentication Service Invalid or missing currency code 1023 Buyer Authentication Service merchant status for 3D secure is invalid 1041 Buyer Authentication Service Validate Authentication failed: missing or invalid PARES 1042 Buyer Authentication Service Validate Authentication failed: PARES format is invalid 1043 Buyer Authentication Service Validate Authentication failed: Cannot find successful Verify Enrollment 1044 Buyer Authentication Service Validate Authentication failed: Signature validation failed for PARES 52 VeriSign, Inc /Rev. 3 DRAFT

65 Chapter 4 Responses to Credit Card Transaction Requests Table 4-2 VeriSign transaction RESULT values and RESPMSG text RESULT RESPMSG and Explanation 1045 Buyer Authentication Service Validate Authentication failed: Mismatched or invalid amount in PARES 1046 Buyer Authentication Service Validate Authentication failed: Mismatched or invalid acquirer in PARES 1047 Buyer Authentication Service Validate Authentication failed: Mismatched or invalid Merchant ID in PARES 1048 Buyer Authentication Service Validate Authentication failed: Mismatched or invalid card number in PARES 1049 Buyer Authentication Service Validate Authentication failed: Mismatched or invalid currency code in PARES 1050 Buyer Authentication Service Validate Authentication failed: Mismatched or invalid XID in PARES 1051 Buyer Authentication Service Validate Authentication failed: Mismatched or invalid order date in PARES 1052 Buyer Authentication Service Validate Authentication failed: This PARES was already validated for a previous Validate Authentication transaction RESULT Values for Communications Errors A value for RESULT 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. Either the VeriSign server is unavailable, or incorrect server/socket pairs have been specified. A value of -1 can also result when there are Internet connectivity errors. Refer other errors to VeriSign at [email protected]. Table 4-3 RESULT values for communications errors RESULT Description -1 Failed to connect to host -2 Failed to resolve hostname -5 Failed to initialize SSL context -6 Parameter list format error: & in name DRAFT VeriSign, Inc /Rev. 3 53

66 VeriSign Payment Services Payflow Pro Developer s Guide Table 4-3 RESULT values for communications errors (Continued) RESULT Description -7 Parameter list format error: invalid [ ] name length clause -8 SSL failed to connect to host -9 SSL read failed -10 SSL write failed -11 Proxy authorization failed -12 Timeout waiting for response -13 Select failure -14 Too many connections -15 Failed to set socket options -20 Proxy read failed -21 Proxy write failed -22 Failed to initialize SSL certificate -23 Host address not specified -24 Invalid transaction type -25 Failed to create a socket -26 Failed to initialize socket layer -27 Parameter list format error: invalid [ ] name length clause -28 Parameter list format error: name -29 Failed to initialize SSL connection -30 Invalid timeout value -31 The certificate chain did not validate, no local certificate found -32 The certificate chain did not validate, common name did not match URL -99 Out of memory 54 VeriSign, Inc /Rev. 3 DRAFT

67 rte Chap CHAPTER 5 5Testing Payflow Pro Credit Card Transactions To test your application, direct all transactions to test-payflow.verisign.com. Transactions directed to this URL are processed through VeriSign s simulated payment network, enabling you to test the configuration and operation of your application or storefront no money changes hands. (You must activate your account and configure your application for live transactions before accepting real orders.) Note New Payflow accounts include a Trail version of the Fraud Protection Services at no charge. This means that you might encounter Result 126 for transactions that triggered the test Fraud Protection filters. Result 126 is intended to give you an idea of the kind of transaction that is considered suspicious so you can evaluate whether you can benefit from using the Fraud Protection Services. For more information, see the chapter entitled Assessing Transactions that Triggered Filters in VeriSign User s Guide for Payflow Pro with Fraud Protection Services. Testing Guidelines + While testing, use only the credit card numbers listed in this chapter. Other numbers produce an error. + Expiration Date must be a valid date in the future (use the mmyy format). + To view the credit card processor that you have selected for testing, see Account Info Processor Info in VeriSign Manager. VeriSign, Inc /Rev DRAFT

68 VeriSign Payment Services Payflow Pro Developer s Guide Credit Card Numbers Used for Testing Use the following credit card numbers for testing. Any other card number produces a general failure. Table 5-1 Test credit card numbers American Express American Express Amex Corporate Australian BankCard Diners Club Diners Club Discover Discover JCB JCB MasterCard MasterCard Visa Visa Visa Note: Even though this number has a different character count than the other test numbers, it is the correct and functional number. Processor-specific Cards Switch/Solo (Paymentech) Testing Result Codes Responses You can use the amount of the transaction to generate a particular Result code. Table 5-2 lists the general guidelines for specifying amounts. Table 5-3 lists VeriSign result codes that are supported by this testing mechanism. 56 VeriSign, Inc /Rev. 3 DRAFT

69 Chapter 5 Testing Payflow Pro Credit Card Transactions Note For all Processors except Global Payments Central (MAPP), PBS, and FDRA: Credit (C) and Force (F) transactions will always be approved regardless of dollar amount or card number. Table 5-2 Result codes resulting from amount submitted Amount Result (RESPMSG) $0 $ (Approved) $1001 $2000 Certain amounts in this range will return specific VeriSign result codes, and can be generated by adding $1000 to that result code. For example, for Result 13 (Referral), submit the amount If the amount is in this range but does not correspond to a VeriSign result code supported by this testing mechanism, result 12 (Declined) is returned. $ Decline VeriSign Result Codes Returned Based on Transaction Amount This table lists the VeriSign Result codes that you can generate using the amount of the transaction. To generate a specific code, submit an amount of 1000 plus the code number (for example, submit an amount of 1013 for a Result code of 13). Table 5-3 VeriSign result codes supporting the amount control Processor American Express Phoenix American Express APAC Result Codes available for testing 0, 12, 13, 104, 1000 Citibank Singapore 0, 4, 5, 12, 13, 23, 24, 104, 2000 FDMS Nashville 0, 12, 13, 104 FDMS North 0, 4, 5, 12, 13, 23,24,114, 1000 FDMS South 0, 12, 13, 104 FDRA 0, 3, 4, 5, 12, 13, 23, 24, 26, 30, 50, 99, 100, 102, 104, 1000 Global Payments Central 0, 4, 5, 8, 12, 13, 23, 24, 104, 111, 114, 1000 DRAFT VeriSign, Inc /Rev. 3 57

70 VeriSign Payment Services Payflow Pro Developer s Guide Table 5-3 VeriSign result codes supporting the amount control (Continued) Processor Result Codes available for testing Global Payments East 0, 4, 5, 12, 13, 23, 24, 30, 100, 104, 114, 1000 Nova 0, 12, 13, 104 Paymentech New Hampshire 0, 12, 13, 104 Vital 0, 4, 12, 13, 23, 104, 114, 1000 Alternative Methods for Generating Specific Result Codes This table shows another method for obtaining VeriSign result codes. Non-zero results from processors are not returned by VeriSign s servers, and therefore cannot be simulated using the amount. In some cases, you may get certain results using the result code plus 1000 even though this table suggests another means of obtaining the result code. Table 5-4 Obtaining VeriSign result code Result Definition How to test using Payflow Pro 0 Approved Use an AMOUNT of $1000 or less For all Processors except Global Payments Central (MAPP), PBS, and FDRA: Credit (C) and Force (F) transactions will always be approved regardless of dollar amount or card number. 1 User authentication failed Use an invalid PWD 2 Invalid tender Use an invalid TENDER, such as G 3 Invalid transaction type Use an invalid TRXTYPE, such as G 4 Invalid amount Use an invalid AMOUNT, such as 1 5 Invalid merchant information Use an AMOUNT of Applies only to the following processors: Global Payments East and Central, and American Express). 7 Field format error Submit a Delayed Capture transaction with no ORIGID 10 Too many line items OBSOLETE. 12 Declined Use an AMOUNT of 1012 or an AMOUNT of 2001 or more 13 Referral Use an AMOUNT of VeriSign, Inc /Rev. 3 DRAFT

71 Chapter 5 Testing Payflow Pro Credit Card Transactions Table 5-4 Obtaining VeriSign result code (Continued) 19 Original transaction ID not found Submit a Delayed Capture transaction with an invalid ORIGID 22 Invalid ABA number Applies only to ACH transactions submit an invalid ABA number (8 digits) 23 Invalid account number Submit an invalid account number, for example, Invalid expiration date Submit an invalid expiration date, for example, Transaction type not mapped to this host (Processor) 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. 29 Invalid XML document Pass a bad XML document (XMLPay users only). 30 Duplicate Transaction Use an AMOUNT of Only applies to Global Payments East and Central processors. 50 Insufficient funds available Use an amount of Only applies to Paymentech. 99 General error Use an AMOUNT of Only applies to Global Payments East. 100 Invalid transaction returned from host (Processor) Use an AMOUNT of Only applies to Global Payments East and Central. 101 Time-out value too small Set timeout value to Error reading response from host (Processor) 104 Timeout waiting for processor response Use an AMOUNT of Use an AMOUNT of Credit error Attempt to credit an authorization. 108 Void error Attempt to void a captured authorization. 111 Capture error Capture an Authorization transaction twice or attempt to capture a transaction that is not an Authorization transaction. 112 Failed AVS check You cannot generate this RESULT value by submitting an amount of 1112, but must submit a value for AVS that will fail. In production, this error occurs only if your account is configured by VeriSign customer service to use the AVS Deny feature. DRAFT VeriSign, Inc /Rev. 3 59

72 VeriSign Payment Services Payflow Pro Developer s Guide Table 5-4 Obtaining VeriSign result code (Continued) 113 Cannot exceed sales cap Applies to ACH transactions only. 114 CVV2 Mismatch Use an AMOUNT of Only applies to Vital and Global Payments East and Central processors Generic Host (Processor) Error Use an AMOUNT of Does not apply to Nova, American Express, or Global Payments East processors. Testing Address Verification Service (AVS) The VeriSign testing server simulates AVS by returning a value for AVSADDR based on the first three characters of the submitted value for STREET. The testing server returns a value for AVSZIP based on the submitted ZIP value as shown in the table. If STREET starts with 667 or higher or begins with a non-numeric character, then the simulator returns AVSADDR=X, AVSZIP=X. Table 5-5 Testing AVSADDR Submitted Value for STREET Example STREET Value AVSADDR Result Elm Y Main N 667 or higher or begins with a non-numeric character Maple X Table 5-6 Testing AVSZIP Submitted Value for ZIP Example ZIP Value AVSZIP Result Y N Any value (if street address is 667 or higher or begins with a non-numeric character) STREET=79232 Maple, ZIP=20304 X Testing Card Security Code (CVV2) If you submit a value for the card security code (CVV2), the cardholder s bank returns a Yes / No / Not Supported 60 VeriSign, Inc /Rev. 3 DRAFT

73 Chapter 5 Testing Payflow Pro Credit Card Transactions (Y / N / X) response on whether the value matches the number on file at the bank. CSC is described in Card Security Code (CSC) Validation on page 40. Tip Some processors decline failed card security code without returning a CVV2MATCH value. Test the results and check with your processor to determine whether they support CSC checking. For the testing server, the first three characters of the CVV2 value determine the CVV2MATCH result, as shown here. Table 5-7 Testing CVV2MATCH CVV2 Value CVV2MATCH Value 000 Null Y N 601 or higher X Testing TeleCheck Transactions See Appendix B, Performing TeleCheck Electronic Check Transactions. for information on testing TeleCheck transactions. DRAFT VeriSign, Inc /Rev. 3 61

74 VeriSign Payment Services Payflow Pro Developer s Guide 62 VeriSign, Inc /Rev. 3 DRAFT

75 rte Chap CHAPTER 6 6Activating Your Payflow Account When you are ready to activate your VeriSign Payflow Pro account to begin submitting live transactions, follow these steps: 1 Log in to VeriSign Manager at 2 Click the Click Here to Activate Your Account button and follow the on-screen instructions. 3 Point your clients to the Active Payflow Pro servers. In your client applications, change test-payflow.verisign.com to payflow.verisign.com VeriSign, Inc /Rev. 3 63

76 VeriSign Payment Services Payflow Pro Developer s Guide 64 VeriSign, Inc /Rev. 3

77 xi Apend APPENDIX A AProcessors Requiring Additional Transaction Parameters This appendix lists both required and optional parameters supplementary to the common parameter set. In this Appendix American Express on page 65 First Data Merchant Services (FDMS) Nashville on page 67 First Data Merchant Services (FDMS) South on page 69 Nova on page 70 Paymentech on page 71 Vital on page 73 American Express Mail: American Express N. 31st Avenue Phoenix, AZ Phone: VeriSign, Inc /Rev. 3 65

78 VeriSign Payment Services Payflow Pro Developer s Guide Additional Credit Card Parameters, American Express In addition to the Parameters Used in Credit Card Transactions on page 19, American Express accepts the following parameters: Table A-1 American Express additional parameters Parameter Description Required Type Length RECURRING Identifies the transaction as recurring. This value does not activate VeriSign s Recurring Billing Service APIs. If the RECURRING parameter was set to Y for the original transaction, then the setting is ignored when forming Credit, Void, and Force transactions. No Alphanumeric Y or N 1 If you subscribe to VeriSign s 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 VeriSign 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. SWIPE Allows Track 1 and Track 2 data to be passed to enable a card-present transaction. No Alphanumeric VeriSign, Inc /Rev. 3

79 Appendix A Processors Requiring Additional Transaction Parameters First Data Merchant Services (FDMS) Nashville Mail: First Data Corporation 2525 Perimeter Place Drive Suite 123 Nashville, TN Phone: Additional Credit Card Parameters, FDMS Nashville In addition to the Parameters Used in Credit Card Transactions on page 19, FDMS Nashville accepts the following parameters: Table A-2 FDMS Nashville additional parameters Parameter Description Required Type Length INVNUM Merchant invoice number. This reference number (PNREF generated by VeriSign) is used for authorizations and settlements. No Alphanumeric 20 The Acquirer decides if this information will appear on the merchant s bank reconciliation statement. VeriSign, Inc /Rev. 3 67

80 VeriSign Payment Services Payflow Pro Developer s Guide Table A-2 FDMS Nashville additional parameters (Continued) Parameter Description Required Type Length RECURRING Identifies the transaction as recurring. This value does not activate VeriSign s Recurring Billing Service APIs. If the RECURRING parameter was set to Y for the original transaction, then the setting is ignored when forming Credit, Void, and Force transactions. No Alphanumeric Y or N 1 If you subscribe to VeriSign s 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 VeriSign 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. SWIPE Allows Track 1 and Track 2 data to be passed to enable a card-present transaction. No Alphanumeric VeriSign, Inc /Rev. 3

81 Appendix A Processors Requiring Additional Transaction Parameters First Data Merchant Services (FDMS) North Mail: First Data Merchant Services 1307 Walt Whitman Road Melville, New York First Data Merchant Services (FDMS) South Mail: First Data Corporation Business Payment Services Group 4000 Coral Ridge Drive Coral Springs, FL Phone: Additional Credit Card Parameters, FDMS South In addition to the Parameters Used in Credit Card Transactions on page 19, FDMS South accepts the following parameters: Table A-3 FDMS South additional parameters Parameter Description Required Type Length SWIPE Allows Track 1 and Track 2 data to be passed to enable a card-present transaction. No Alphanumeric 80 VeriSign, Inc /Rev. 3 69

82 VeriSign Payment Services Payflow Pro Developer s Guide Nova Mail: Nova Information Systems, Inc. Knoxville Operations Center 7300 Chapman Highway Knoxville, TN Phone: Additional Credit Card Parameters, Nova In addition to the Parameters Used in Credit Card Transactions on page 19, Nova accepts the following parameter: Table A-4 Vital additional parameters Parameter Description Required Type Length RECURRING Identifies the transaction as recurring. This value does not activate VeriSign s Recurring Billing Service APIs. If the RECURRING parameter was set to Y for the original transaction, then the setting is ignored when forming Credit, Void, and Force transactions. No Alphanumeric Y or N 1 If you subscribe to VeriSign s 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 VeriSign 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. 70 VeriSign, Inc /Rev. 3

83 Appendix A Processors Requiring Additional Transaction Parameters Paymentech Mail: Paymentech 4 Northeastern Blvd. Salem, NH Phone: Additional Credit Card Parameters, Paymentech In addition to the Parameters Used in Credit Card Transactions on page 19, Paymentech accepts the following parameters. For best AVS results, pass the city and state parameters in the parameter list. Table A-5 Additional Paymentech parameters Parameter Description Required Type Length CITY Cardholder s billing city. No Alpha 20 INVNUM MERCHDES CR MERCHSVC Merchant invoice number. This reference number (PNREF generated by VeriSign) is used for authorizations and settlements. The Acquirer decides if this information will appear on the merchant s bank reconciliation statement. Merchant descriptor. For example, ABCCMPY*FALLCATALOG Merchant telephone number. For example, No Alphanumeric 20 No Alphanumeric 22 No Alphanumeric 13 STATE Cardholder s billing state. No Alpha 2 SWIPE Allows Track 1 and Track 2 data to be passed to enable a card-present transaction. No Alphanumeric 80 VeriSign, Inc /Rev. 3 71

84 VeriSign Payment Services Payflow Pro Developer s Guide Table A-5 Additional Paymentech parameters (Continued) Parameter Description Required Type Length RECURRING Identifies the transaction as recurring. This value does not activate VeriSign s Recurring Billing Service APIs. 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 VeriSign s 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 VeriSign 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. No Alphanumeric Y or N 1 72 VeriSign, Inc /Rev. 3

85 Appendix A Processors Requiring Additional Transaction Parameters Vital Mail: Phone: Vital Visanet Processing Services 8320 South Hardy Road Tempe, AZ (Help Desk) Additional Credit Card Parameters, Vital In addition to the Parameters Used in Credit Card Transactions on page 19, Vital accepts the following parameters (Table continues on next page).: Table A-6 Vital additional parameters Parameter Description Required Type Length INVNUM Merchant invoice number. This reference number (PNREF generated by VeriSign) is used for authorizations and settlements. No Alphanu meric 20 Use in place of PONUM. The Acquirer decides if this information will appear on the merchant s bank reconciliation statement. SWIPE Allows Track 1 and Track 2 data to be passed to enable a card-present transaction. No Alphanumeric 80 VeriSign, Inc /Rev. 3 73

86 VeriSign Payment Services Payflow Pro Developer s Guide Table A-6 Vital additional parameters (Continued) Parameter Description Required Type Length RECURRING Identifies the transaction as recurring. This value does not activate VeriSign s Recurring Billing Service APIs. 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 VeriSign s 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 VeriSign 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. No Alphanumeric Y or N 1 74 VeriSign, Inc /Rev. 3

87 xi Apend APPENDIX B BPerforming TeleCheck Electronic Check Transactions This chapter describes the process of performing electronic check transactions. Responses to transaction requests are described in Appendix C, Responses to TeleCheck Transaction Requests. VeriSign offers electronic check acceptance through TeleCheck. Before processing electronic check transactions, merchants must obtain an account through TeleCheck ( Note For information on credit card transactions, skip this chapter and see Chapter 3, Performing Credit Card Transactions. For information on performing ACH transactions, contact your VeriSign Sales Representative at [email protected]. TeleCheck Contact Information Mail: Phone: TeleCheck Merchant Services PO Box 4513 Houston, TX (Merchant Services) TeleCheck Transaction Syntax Note The examples in this chapter use the syntax of the pfpro executable client. Other Payflow Pro clients differ in where and how the parameter values are set, but the meaning and uses are the same. VeriSign, Inc /Rev. 3 75

88 VeriSign Payment Services Payflow Pro Developer s Guide Use the following syntax when calling the Payflow Pro client (pfpro) to process a TeleCheck transaction. Table B-1 describes the arguments to the pfpro executable client command pfpro <HostAddress> <HostPort> <ParmList> <TimeOut> <ProxyAddress> <ProxyPort> <ProxyLogon> <ProxyPassword> For example: pfro test-payflow.verisign.com 443 TRXTYPE=S&TENDER=K &PARTNER=VeriSign&VENDOR=SuperMerchant&USER=SuperMerchant&PWD=x1y 2z3&AMT=123.00&MICR= &CHKNUM=4321 &NAME=Lydia Chin&STREET=121 Park Street&CITY=Pleasanton&STATE=MA &ZIP= &DL=MA & [email protected] 30 Table B-1 Arguments to the pfpro executable client Argument Required Description HOSTADDRESS Yes VeriSign s host name. For live transactions, use payflow.verisign.com For testing purposes use test-payflow.verisign.com HOSTPORT Yes VeriSign host port number: Use port 443. PARMLIST Yes The ParmList is the list of parameters that specify the payment information for the transaction. The quotation marks at the beginning and end are required. In the example, the ParmList is: TRXTYPE=S&TENDER=K&PARTNER=VeriSign&VE NDOR=SuperMerchant&USER=SuperMerchant&PW D=x1y2z3&AMT=123.00&MICR= &CHKNUM=4321&NAME=Lydia Chin&STREET=121 Park Street&CITY=Pleasanton&STATE=MA&ZIP= &DL=MA & [email protected] All parameters used in TeleCheck transactions are described in Table B-2 on page 78. TIMEOUT Yes Time-out period for the transaction. The minimum recommended time-out value is 30 seconds. The VeriSign client begins tracking from the time that it sends the transaction request to the VeriSign server. PROXYADDRESS No Proxy server address. Use the PROXY parameters for servers behind a firewall. Your network administrator can provide the values. PROXYPORT No Proxy server port 76 VeriSign, Inc /Rev. 3

89 Appendix B Performing TeleCheck Electronic Check Transactions Table B-1 Arguments to the pfpro executable client Argument Required Description PROXYLOGON No Proxy server logon ID PROXYPASSWORD No Proxy server logon password Command Syntax Guidelines Follow these guidelines: + The command must be a single string with no line breaks. + Use spaces as argument separators. + Enclose the ParmList in quotation marks ( ). + Quotation marks ( ) are absolutely not allowed in the body of the ParmList. + Separate all name/value pairs in the ParmList using an ampersand (&). + Payflow Pro supports UTF-8 format for values passed in name=value pairs. + Calling pfpro without the required parameters results in an error message. Using Special Characters in Values Because the ampersand (&) and equal sign (=) characters have special meanings in the ParmList, name/value pairs like NAME=Ruff & Johnson, and COMMENT1=Level=5 are not valid. To use the & and = characters in the value of a name/value pair, use a length tag. A length tag specifies the exact number of characters and spaces that appear in the value. The following name/value pairs are valid: NAME[14]=Ruff & Johnson COMMENT1[7]=Level=5 Note Quotation marks ( ) are absolutely not allowed in the body of the ParmList, even if you use length tags. TeleCheck Parameters Parameters used for processing electronic checks through TeleCheck are described in Table B-2. Required and optional parameters are noted. VeriSign, Inc /Rev. 3 77

90 VeriSign Payment Services Payflow Pro Developer s Guide Note Appendix E, Additional Reporting Parameters, provides a list of parameters that you can pass for reporting purposes. Required Parameters As a summary of Table B-2, the following parameters are required for every electronic check transaction: TRXTYPE TENDER CHKTYPE PARTNER VENDOR USER PWD AMT CITY DL or SS CHKNUM MICR NAME STATE STREET ZIP Table B-2 TeleCheck Parameters Parameter Description Required Type Length AMT This is the transaction amount in 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 not 1, Yes Numeric US Dollars only. 7 CITY Account holder s city Yes Alpha 20 COMMENT1 User-defined value for reporting and auditing purposes. No Alphanumeric 128 COMMENT2 User-defined value for reporting and auditing purposes. No Alphanumeric VeriSign, Inc /Rev. 3

91 Appendix B Performing TeleCheck Electronic Check Transactions Table B-2 TeleCheck Parameters (Continued) Parameter Description Required Type Length CHKNUM Account holder s next unused (available) check number Yes Numeric 7 CHKTYPE Check type: P: personal (default) or C: company Yes Alpha If CHKTYPE=P, then a value for either DL or SS must be passed as an identifier. If CHKTYPE=C, then the Federal Tax ID must be passed as the SS value. DL Driver s license number. If CHKTYPE=P, a value for either DL or SS must be passed as an identifier. Yes Alphanumeric 33 Format: XXnnnnnnnn XX = State Code nnnnnnnn = DL Number DOB Account holder s date of birth. Format: mmddyyyy. For example, July 28, 1965 is represented as No Alphanumeric 8 Account holder s address Yes Alphanumeric INVNUM Check invoice number No Alphanumeric MICR Magnetic Ink Check Reader. This is the entire line of numbers at the bottom of all checks. It includes the transit number, account number, and check number. Yes Alphanumeric 35 NAME Account holder s name as it appears on the check Yes Alphanumeric 30 PARTNER The authorized VeriSign Reseller that registered you for the Payflow Pro service provided you with a Partner ID. If you registered yourself, use VeriSign. Yes Alphanumeric 12 This parameter is case-sensitive. PHONENUM Account holder s telephone number No Numeric 20 VeriSign, Inc /Rev. 3 79

92 VeriSign Payment Services Payflow Pro Developer s Guide Table B-2 TeleCheck Parameters (Continued) Parameter Description Required Type Length PWD Case-sensitive 6- to 32-character password that you created while registering for the account. Yes Alphanumeric 32 SS Account holder s social security number. No Alphanumeric 35 If CHKTYPE=P, a value for either DL or SS must be passed as an identifier. If CHKTYPE=C, the Federal Tax ID must be passed as the SS value. STATE Account holder s state Yes Alpha 2 STREET Account holder s street address Yes Alphanumeric 30 TENDER TRXTYPE Tender type (method of payment). Use only the value K (electronic check). Type of transaction that should be processed. Allowed transaction types: Sale (S), Void (V), Inquiry (I). Yes Alpha 1 Yes Alpha 1 USER Case-sensitive login ID for the Payflow account that you created while registering for the account. Yes Alphanumeric 12 In the future, each account will allow multiple users. This parameter will specify the user. VENDOR Case-sensitive Vendor ID that you created while registering for the account. Yes Alphanumeric 12 ZIP Account holder s 5- to 9-digit postal code (called ZIP code in the USA). Do not use spaces, dashes, or non-numeric characters. Yes Alpha 9 Testing TeleCheck Transactions VeriSign provides a test server to support testing and configuration. 80 VeriSign, Inc /Rev. 3

93 Appendix B Performing TeleCheck Electronic Check Transactions Test Transaction Server Submit test transactions to test-payflow.verisign.com, using port 443. Example Test Transaction TRXTYPE=S&TENDER=K&CHKTYPE=P&PARTNER=<your Partner Name (typically VeriSign>&VENDOR=<your Merchant Login Name>&USER=<your Merchant Login Name>&PWD=<your Payflow Pro password>& AMT=42.00&STREET=1234 Main&CITY=Buffalo&DL=CA123456&CHKNUM=1001&EM AIL=<your address>&micr=<use a MICR value from Table B-3>&NAME=Sally&STATE=CA&ZIP=95050 Table B-3 MICR values for testing MICR HOSTCOD E TeleCheck Result Check Approved ECA Check Approved No ECA Check Approved ECA, No Guarantee Check Approved No ECA, No Guarantee Check Decline Negative Data Check Decline Scoring Check Failed 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 to [email protected]. Be sure to include the following information: + Your test Web site address where test transactions can be processed + The name, address, and phone number of the person to contact about any needed corrections. The certification process usually takes 2-3 days. Use the HostAddress value of payflow.verisign.com and HostPort of 443 VeriSign, Inc /Rev. 3 81

94 VeriSign Payment Services Payflow Pro Developer s Guide Logging Transaction Information VeriSign maintains a record of all transactions executed on your account. Note This record is not the official bank statement. The transaction summary that you receive from TeleCheck is the official record. Use VeriSign Manager at to view this record and use the information to help reconcile your accounting records. In addition, VeriSign strongly recommends that you log all transaction results (except for check information) on your own system. At a minimum, log the following data: + PNREF + Transaction Date + Transaction Amount + HOSTCODE If you have any questions regarding a transaction, reference the PNREF (also called the transaction ID). 82 VeriSign, Inc /Rev. 3

95 xi Apend APPENDIX C CResponses to TeleCheck Transaction Requests This chapter describes the contents of a response to a TeleCheck transaction request. When a transaction finishes, VeriSign returns a response string made up of name/value pairs. For example: RESULT=0&PNREF=VXYZ &HOSTCODE=000500&RESPMSG=Approved Transaction response values are described in Table C-1. Table C-1 Transaction responses common to all tender types Field Description Type Length RESULT The outcome of the attempted transaction. A result of 0 (zero) indicates the transaction was approved. Any other number indicates a decline or error. RESULT codes are described in RESULT Codes and RESPMSG Values on page 47. Numeric Variable PNREF VeriSign Reference ID, a unique number that identifies the transaction. PNREF is described in HOSTCODE Values on page 83. Alphanumeric 12 HOSTCODE TeleCheck s response code representing the results of the transaction authorization attempt. These values are described in HOSTCODE Values on page 83. Numeric 6 RESPMSG A descriptive message associated with decline or error RESULTs. Response messages are described in RESULT Codes and RESPMSG Values on page 47. Alphanumeric Variable HOSTCODE Values The HOSTCODE reflects the TeleCheck server result. The following tables describe the HOSTCODE values. TeleCheck requires that you display certain verbiage to the VeriSign, Inc /Rev. 3 83

96 VeriSign Payment Services Payflow Pro Developer s Guide purchaser based on the returned HOSTCODE value check with TeleCheck for details. Note Many of these codes will not be encountered under normal operating conditions they are included as a troubleshooting aid. In the tables, the Frequency column indicates the likelihood that you will encounter the code. Table C-2 Sale Approved HOSTCODE values Code Response Description Frequency Sale Approved Sale Approved by credit card network Sale Time-out Sale transaction time-out in credit card network Test Card Test card sale approved (never billed) Common Common Common ANI Sale Approved 900/Telco sale approved ANI bill only PB Sale Approved Private billing sale approved PB only Sale Approved Direct Check Sale/ECA approved Direct Check Sale Approved Direct Check Sale approved (no ECA) Sale Approved Direct Check Sale/ECA approved no guarantee Sale Approved Direct Check Sale approved no ECA no guarantee Direct Check Direct Check Direct Check Table C-3 Sale Declined HOSTCODE values Code Response Description Frequency Sale Declined Sale declined by credit card network Common Sale Rejected Sale does not meet risk standards Common Check Declined Direct Check Sale declined negative data Direct Check 84 VeriSign, Inc /Rev. 3

97 Appendix C Responses to TeleCheck Transaction Requests Table C-3 Sale Declined HOSTCODE values Code Response Description Frequency Check Declined Direct Check Sale Decline Scoring Direct Check Check Failure Direct Check Sale Direct Check Table C-4 Inquiry Approved HOSTCODE values Code Response Description Frequency OTB Approved Preauth approved. AVS matches if provided No Response No response from credit card network for preauth. Common Common AVS Time-out Preauth approved, AVS timed out AVS only PB Approved Private billing approved. PB only Positive Record Previous positive history. Common Test card Approved Test Card Common OTB/AVS Approval Preauth Approved, AVS match AVS only ANI Bill approved 900/TELCO billing approved ANI bill only Table C-5 General Failure HOSTCODE values Code Response Description Frequency General Failure General host based failure Rare Invalid Value Invalid for one or more fields in transaction Unknown Response TeleCheck received an unknown response Common Rare Table C-6 Inquiry Declined HOSTCODE values Code Response Description Frequency Preauth Declined Declined by credit card or Telco network (LIDB) PIN Mismatch Mismatch on PIN stored in TeleCheck database Common Not Used VeriSign, Inc /Rev. 3 85

98 VeriSign Payment Services Payflow Pro Developer s Guide Table C-6 Inquiry Declined HOSTCODE values Code Response Description Frequency Negative Card Record Temporary and permanent blocks. Prior OTB decline, sale decline or CS block Transaction falls below minimum scoring standards. Most frequently used for risk scoring declines, where a transaction falls below minimum standards. Common Negative ANI Record ANI previously blocked by CS Common Chargeback Card Card with chargeback history Common Chargeback ANI ANI with chargeback history Common Exceed card profile 1 Card has exceeded usage limits Uncommon Too many Cards 1 ANI has excessive number of cards Uncommon Exceed ANI profile 1 ANI has exceeded usage limits Uncommon Too Many Phones 1 Card has been used from excessive ANI Uncommon OTB/AVS Decline OTB decline and AVS mismatch AVS OTB only OTB/AVS Decline OTB approved and AVS mismatch AVS OTB only OTB/AVS Decline OTB decline and AVS match AVS OTB only Risk Referral Temporary Risk referral, AVS necessary Card Not Qualified Card does not meet minimum bank restrictions PB Risk Referral Private billing risk referral, AVS necessary Common Not Used PB Only 1 This data is included in risk scoring decisions and a response of 210 has higher precedence. 86 VeriSign, Inc /Rev. 3

99 xi Apend APPENDIX D DSubmitting Purchasing Card Level 2 and Level 3 Transactions VeriSign 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 items details are included in the transaction, VeriSign 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. About Purchasing Cards Purchasing Cards are used in the procurement process to eliminate paper-based order systems and associated costs, to improve control and accountability through itemized statements, to foster better risk controls through spending limits and buying from approved vendors, to reduce administrative overhead because employees are empowered to make small purchases, and to enable enterprises to negotiate better contract pricing and discounts with suppliers through the use of vendor detail reports. To promote acceptance and usage of Purchasing Card programs, card issuers have established incentive rates for merchants. These rates are available for merchants who comply at either Level 2 or Level 3 (described in the next section). Transactions that comply at Level 1 qualify as a normal credit card transactions. VeriSign, Inc /Rev. 3 87

100 VeriSign Payment Services Payflow Pro Developer s Guide Note Card issuing institutions perform strict data verification on the enhanced data that is submitted with Level 2 or Level 3 transactions. Issuers may charge stiff penalties if 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. Note The American Express APAC processing platform does not support Level 2 and Level 3 transaction data. The following transaction levels are recognized: Level 1: 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. Level 2: 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. Level 3: 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. VeriSign 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 BIN ranges for Purchasing cards. Sometimes the determination of whether a card is a Purchasing card is left to the processor (for example, Vital). In other cases, the VeriSign Payment Gateway 88 VeriSign, Inc /Rev. 3

101 Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions makes the determination based on the BIN range (for example, FDMS South and AMEX). Performing American Express Purchasing Card Transactions Through the American Express Processor The information in this section applies to transactions processed by the American Express Processor, 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 Auth transactions is ignored. The VeriSign Payment Gateway decides whether a transaction meets Level 3 requirements during authorization. Level 3 data is passed to the AMEX processor only during settlement. Avoiding Downgrade If a transaction uses the Purchasing card BIN range and contains a line item, but does not include all mandatory Level 3 parameters, then 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 MEDIUM or HIGH, a message like the following is returned in the ADDLMSGS field: Features not processed: PCARD L3 (missing or invalid: InvoiceNumber RequestorName) or Features not processed: PCARD L3 (line-item 3 missing: Description) Submitting Successful Level 3 Transactions If a transaction uses the Purchasing card BIN range, contains all mandatory Level 3 fields, and has at least one line item (with all mandatory line item fields), the VeriSign Payment Gateway flags it as Level 3. VeriSign, Inc /Rev. 3 89

102 VeriSign Payment Services Payflow Pro Developer s Guide Edit Check VeriSign 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 is the total amount for the transaction, AMT. Total Tax Amount is TAXAMT. Total Freight Amount is FREIGHTAMT, or, if not present, the summation of L_FREIGHTAMT for all line items. Total Handling Amount is HANDLINGAMT, or, if not present, the summation of L_HANDLINGAMT for all line items. Total Line-Item Amount is the summation of L_QTYn * L_COSTn for all line items (n as the line item number). For example, if there are 2 line items, then the Total Line-item Amount would be (LQTY1*LCOST1) + (LQTY2*LCOST2) Accepted BIN Ranges The following Bank Identification Numbers (BINs) are accepted for American Express Level 2 and Level 3 transactions: VeriSign, Inc /Rev. 3

103 Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions American Express Level 2 Transaction Data Table D-1 American Express Level 2 transaction data Pay Flow Pro SDK parameter Mandatory / Optional Format (min/max, type) PONUM M 1/17, A/N SHIPTOZIP M 1/16, A/N DESC1 O 1/40, A/N DESC2 O 1/40, A/N DESC3 O 1/40, A/N DESC4 (Typically used to pass the freight amount as FRT<amount> (for example, FRT10.0.). M 1/40, A/N Example American Express Level 2 Transaction Parameter List "TRXTYPE=S&ACCT= &AMT=20.06&CITY=Mountain View&DESC1=desc1&DESC2=desc2&DESC3=desc3&DESC4=FRT10.00&EXPDATE= 1209&NAME=Cardholder Name&PARTNER=verisign&PONUM=12345&PWD=pwd&SHIPTOZIP=94045&STATE= CA&STREET=123 Main St.&TENDER=C&USER=user&ZIP= " American Express Level 3 Transaction Data VeriSign 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 Table D-2. Table D-2 American Express Level 3 Parameters AMEX Name (per American Express Specification) Mandatory / Optional Pay Flow Pro SDK parameter XMLPayRequest parameter (SeeVeriSign XMLPay 4.2 Core Specification for detailed instructions.) Format (min/max, type) Supplier Reference Number O INVNUM Defaults to PNREF if not present. Invoice.InvNum 1/20, A/N Card Account No M ACCT Card.CardNum VeriSign, Inc /Rev. 3 91

104 VeriSign Payment Services Payflow Pro Developer s Guide Table D-2 American Express Level 3 Parameters (Continued) AMEX Name (per American Express Specification) Mandatory / Optional Pay Flow Pro SDK parameter XMLPayRequest parameter (SeeVeriSign XMLPay 4.2 Core Specification for detailed instructions.) Format (min/max, type) Authorization Code M AUTHCODE (Passed transparently for delayed capture. Use only with voice authorized force capture transactions) ForceCapture.Authcode Requester Name M REQNAME ExtData REQNAME 1/40, A/N Cardmember Reference No Purchase Order Num M PONUM BillTo.PONum 1/17, A/N M PONUM BillTo.PONum 1/17, A/N Ship to ZIP M SHIPTOZIP ShipTo.Address.ZIP 5/6, A/N Invoice Date O INVOICEDATE Defaults to Transaction Date if not present. Invoice.Date YYYYMMD D, string Exp Date M EXPDATE Card.ExpDate Total Transaction Amount M AMT The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators ( not 1,234.56). Invoice.TotalAmt 1/8 NUM Total Tax Amount M TAXAMT The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators ( not 1,234.56). Invoice.TaxAmt 1/6 NUM 92 VeriSign, Inc /Rev. 3

105 Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions Table D-2 American Express Level 3 Parameters (Continued) AMEX Name (per American Express Specification) Mandatory / Optional Pay Flow Pro SDK parameter XMLPayRequest parameter (SeeVeriSign XMLPay 4.2 Core Specification for detailed instructions.) Format (min/max, type) Charge Description O DESC Defaults to NO Invoice.Description 1/40, A/N Total Freight Amt O FREIGHTAMT Invoice.FreightAmt 1/15, A/N Total Handling Amt O HANDLINGAMT Invoice.HandlingAmt 1/15, A/N Quantity Invoiced M L_QTY Item.Quantity 1/10, NUM Unit of Measure M L_UOM Item.UnitOfMeasurement 2/2, A/N Unit Price M L_COST Item.UnitPrice 1/15, NUM Item Description M L_DESC Item.Description 1/80, A/N Supplier Catalog No M L_CATALOGNUM Item.CatalogNumber 1/20, A/N Cost Center No M L_COSTCENTERNUM Item.CostCenterNumber 1/30, A/N Supplier Stock Keeping Unit Number Universal Product Code O L_PRODCODE Item.SKU 1/30, A/N O L_UPC Item.UPC 1/30, A/N Item Tax Amount O L_TAXAMT Item.TaxAmt 1/6, NUM Freight Amount O L_FREIGHTAMT Item.FreightAmt 1/15, NUM Handling Amount O L_HANDLINGAMT Item.HandlingAmt 1/15, NUM Tracking Number O L_TRACKINGNUM Item.TrackingNumber 1/30, A/N Drop-off Address1 O L_PICKUPSTREET Item.PickUp.Address.Street 1/40, A/N Drop-off City O L_PICKUPCITY Item.PickUp.Address.City 2/30, A/N Drop-off State O L_PICKUPSTATE Item.PickUp.Address.State 2/2, A/N Drop-off ZIP O L_PICKUPZIP Item.PickUp.Address.ZIP 3/15, A/N Drop-off Country O L_PICKUPCOUNTRY Item.PickUp.Address.Country 2/3, A/N VeriSign, Inc /Rev. 3 93

106 VeriSign Payment Services Payflow Pro Developer s Guide Table D-2 American Express Level 3 Parameters (Continued) AMEX Name (per American Express Specification) Mandatory / Optional Pay Flow Pro SDK parameter XMLPayRequest parameter (SeeVeriSign XMLPay 4.2 Core Specification for detailed instructions.) Format (min/max, type) UNSPSC Code O L_UNSPSCCODE Item.UNSPSCCode 1/30, A/N Example American Express Level 3 SDK Transaction Parameter List "TRXTYPE=S&TENDER=C&partner=partner&PWD=test&USER=test&ACCT= &EXPDATE=1213&AMT=5.00&COMMENT1=PCARD Test&COMMENT2=Hi KC&ZIP= &STREET=123 KC WAY&CVV2=052&COUNTRYCODE=USA&CUSTCODE=12345&FREIGHTAMT=1.00& ORDERDATE=021700&HANDLINGAMT=1.00&PONUM= &SHIPFROMZIP= &SHIPTOZIP= &TAXAMT=1.00&TAXEXEMPT =N&L_UPC1=PN&L_QTY1=1&L_DESC1=Test 123&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_COST2= 1.00&L_PRODCODE2=1234&L_COSTCENTERNUM2=55&L_TAXAMT2=1.00&REQNA ME=Robert&SHIPTOZIP=543210&INVNUM= &VERBOSITY=2" Example American Express Level 3 XMLPay Transaction <?xml version="1.0"?> - <XMLPayRequest Timeout="30"> - <RequestData> <Vendor>VENDOR</Vendor> <Partner>PARTNER</Partner> - <Transactions> - <Transaction CustRef="CUST "> - <Sale> - <PayData> - <Invoice> <InvNum> </InvNum> <Date> </Date> <ExtData Name="REQNAME" Value="[email protected]" /> 94 VeriSign, Inc /Rev. 3

107 Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions - <BillTo> <PONum>PO </PONum> <Name>John</Name> - <Address> <Street>123 Test</Street> <City>Mountian View</City> <State>CA</State> <Zip>12345</Zip> <Country>840</Country> </Address> < >[email protected]</ > </BillTo> - <ShipFrom> - <Address> <Street>456 Test</Street> <City>Mountian View</City> <State>CA</State> <Zip>543210</Zip> </Address> </ShipFrom> - <ShipTo> - <Address> <Street>789 Test</Street> <City>Mountian View</City> <State>CA</State> <Zip>99999</Zip> <Country>840</Country> </Address> VeriSign, Inc /Rev. 3 95

108 VeriSign Payment Services Payflow Pro Developer s Guide </ShipTo> - <Items> - <Item Number="1"> <SKU>EAD240</SKU> <UPC>67899</UPC> <Description>Ducati parts</description> <Quantity>2</Quantity> <UnitPrice>.10</UnitPrice> <UnitOfMeasurement>10</UnitOfMeasurement> <CostCenterNumber>5000</CostCenterNumber> <TrackingNumber>TR42322</TrackingNumber> <UNSPSCCode>UNSPSC001</UNSPSCCode> <CatalogNumber>1551</CatalogNumber> - <PickUp> - <Address> <Street>112 Pickup Ave</Street> <City>Pickup City</City> <State>CA</State> <Zip>94043</Zip> <Country>840</Country> </Address> </PickUp> <FreightAmt>0.50</FreightAmt> <HandlingAmt>0.50</HandlingAmt> </Item> - <Item Number="2"> <SKU>42335</SKU> <UPC>45578</UPC> 96 VeriSign, Inc /Rev. 3

109 Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions <Description>Honda Parts</Description> <Quantity>1</Quantity> <UnitPrice>.10</UnitPrice> <UnitOfMeasurement>50</UnitOfMeasurement> <CostCenterNumber>5003</CostCenterNumber> <TrackingNumber>TR34225</TrackingNumber> <UNSPSCCode>UNSPSC002</UNSPSCCode> <CatalogNumber>1555</CatalogNumber> - <PickUp> - <Address> <Street>113 Pickup Ave</Street> <City>Pickup City</City> <State>CA</State> <Zip>94043</Zip> <Country>840</Country> </Address> </PickUp> <FreightAmt>0.50</FreightAmt> <HandlingAmt>0.50</HandlingAmt> </Item> - <Item Number="3"> <SKU>12347</SKU> <UPC>54329</UPC> <Description>Harley Parts</Description> <Quantity>2</Quantity> <UnitPrice>.10</UnitPrice> <UnitOfMeasurement>15</UnitOfMeasurement> <CostCenterNumber>5009</CostCenterNumber> VeriSign, Inc /Rev. 3 97

110 VeriSign Payment Services Payflow Pro Developer s Guide <TrackingNumber>TR32223</TrackingNumber> <UNSPSCCode>UNSPSC003</UNSPSCCode> <CatalogNumber>1560</CatalogNumber> - <PickUp> - <Address> <Street>114 Pickup Ave</Street> <City>Pickup City</City> <State>CA</State> <Zip>94043</Zip> <Country>840</Country> </Address> </PickUp> <FreightAmt>0.50</FreightAmt> <HandlingAmt>0.50</HandlingAmt> </Item> </Items> <Description>CAR PARTS</Description> <TaxAmt>1.60</TaxAmt> <TotalAmt>5.10</TotalAmt> </Invoice> - <Tender> - <Card> <CardType>AMEX</CardType> <CardNum> </CardNum> <ExpDate>201312</ExpDate> </Card> </Tender> </PayData> 98 VeriSign, Inc /Rev. 3

111 Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions </Sale> </Transaction> </Transactions> </RequestData> - <RequestAuth> - <UserPass> <User>USER</User> <Password>PASSWORD</Password> </UserPass> </RequestAuth> </XMLPayRequest> Performing Purchasing Card Transactions, First Data Merchant Services (FDMS) Nashville The following parameters are recommended to obtain the best rates for purchasing card transactions with FDMS Nashville. Table D-3 FDMS commercial card parameters Parameter Description Required Type Length COMMCARD One-character value representing type of purchasing card account number sent. P Purchase Card C Corporate Card B Business Card U Unknown (default) N None No (defaults to U - Unknown) Alphanumeric 1 DUTYAMT 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 ( not 1,234.56). No Currency 10 VeriSign, Inc /Rev. 3 99

112 VeriSign Payment Services Payflow Pro Developer s Guide Table D-3 FDMS commercial card parameters (Continued) Parameter Description Required Type Length FREIGHTAMT Freight Amount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators ( not 1,234.56). No Currency 10 PONUM Purchase Order Number. No (but provides best rate when used) Alphanumeric 25 SHIPTOZIP Ship to postal code (called ZIP code in the USA). No (but provides best rate when used) Numeric 9 TAXAMT Tax Amount The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators ( not 1,234.56). No (but provides best rate when used) Currency 10 If a purchase is exempted from tax, then you must send TAXEXEMPT=Y&TAXAMT=0.00. TAXEXEMPT Is the customer tax exempt? Y or N If a purchase is exempted from tax, then you must send TAXEXEMPT=Y&TAXAMT=0.00. No Alpha VeriSign, Inc /Rev. 3

113 Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions Performing Purchasing Card Transactions, First Data Merchant Services (FDMS) North The following parameters are recommended to obtain the best rates for purchasing card transactions (Level 2/3) with FDMS North: Table D-4 FDMS North purchase card parameters Parameter Description Required Type Length COUNTRYCODE Destination Country Code. Visa and MasterCard are different. Refer to Country Code tables. (See Appendix G, ISO Country Codes. ) No Alpha 3 DISCOUNT Discount amount on total sale No Currency 10 DUTYAMT FREIGHTAMT 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 ( not 1,234.56). See FDMS South Currency Codes and Decimal Positions on page 153. 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 ( not 1,234.56). See FDMS South Currency Codes and Decimal Positions on page 153. No Currency 10 No Currency 10 PONUM Purchase Order Number / Merchant related data No (but provides best rate when used) Alphanumeric 25 SHIPFROMZIP The postal code (called ZIP code in the USA) from which shipping occurs. No (but provides best rate when used) Numeric 9 VeriSign, Inc /Rev

114 VeriSign Payment Services Payflow Pro Developer s Guide Table D-4 FDMS North purchase card parameters (Continued) Parameter Description Required Type Length SHIPTOZIP Ship to postal code (called ZIP code in the USA). No (but provides best rate when used) Numeric 9 TAXAMT Tax Amount The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators ( not 1,234.56). See FDMS South Currency Codes and Decimal Positions on page 153. No (but provides best rate when used) Currency 10 If a purchase is exempted from tax, then you must send TAXEXEMPT=Y&TAXAMT=0.00. Purchase Card Line Item Parameters, FDMS North 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 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. In addition, the SHIPFROMZIP parameter is required for Level 3 transactions. Table D-5 Purchase card line item parameters Parameter Description Required Type Length L_QTYn Quantity (whole units only) Yes Numeric 10 L_COMMCODEn Item commodity code No Alphanumeric L_DESCn Item description No Alphanumeric L_UOMn Item unit of measure. See Units of Measure on page 147. No Alpha 3 L_COSTn Cost per item, excluding tax No Currency 10 L_UPCn Supplier specific product code No Alphanumeric VeriSign, Inc /Rev. 3

115 Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions Table D-5 Purchase card line item parameters (Continued) Parameter Description Required Type Length L_DISCOUNTn Discount per line item No Currency 10 L_AMTn Total line item amount including tax and discount. + for debit, - for credits Yes Currency 10 L_TAXAMTn Line item Tax amount No Currency 10 Performing Purchasing Card Transactions, First Data Merchant Services (FDMS) South The following parameters are recommended to obtain the best rates for purchasing card transactions (Level 2/3) with FDMS South: Table D-6 FDMS South purchase card parameters Parameter Description Required Type Length CITY Cardholder s city. No Alpha 13 COUNTRYCODE Destination Country Code. Visa and MasterCard are different. Refer to Country Code tables. (See Appendix G, ISO Country Codes. ) No Alpha 3 CUSTCODE Customer code/customer reference ID No Alphanumeric 17 DISCOUNT Discount amount on total sale No Currency 10 DUTYAMT 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 ( not 1,234.56). See FDMS South Currency Codes and Decimal Positions on page 153. No Currency 10 FIRSTNAME Cardholder s first name. No Alpha 15 VeriSign, Inc /Rev

116 VeriSign Payment Services Payflow Pro Developer s Guide Table D-6 FDMS South purchase card parameters (Continued) Parameter Description Required Type Length FREIGHTAMT 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 ( not 1,234.56). See FDMS South Currency Codes and Decimal Positions on page 153. No Currency 10 INVNUM Merchant invoice number. This reference number (PNREF generated by VeriSign) is used for authorizations and settlements. No Alphanumeric 20 The Acquirer decides if this information will appear on the merchant s bank reconciliation statement. LASTNAME Cardholder s last name. No Alpha 15 ORDERDATE Order date Format is mmddyy with no slashes or dashes. For example, July 28, 2003 is No Numeric 6 ORDERTIME Order time and date. Format is either YYYY-MM-DD or YYYY-MM-DD HH:MI:SS (where HH is in 24-hour time). No Alphanu meric 19 If the value does not conform to one of the formats or if the date is not valid (for example, ), 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. 104 VeriSign, Inc /Rev. 3

117 Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions Table D-6 FDMS South purchase card parameters (Continued) Parameter Description Required Type Length PONUM Purchase Order Number / Merchant related data No (but provides best rate when used) Alphanumeric 25 SHIPFROMZIP The postal code (called ZIP code in the USA) from which shipping occurs. No (but provides best rate when used) Numeric 9 SHIPTOZIP Ship to postal code (called ZIP code in the USA). No (but provides best rate when used) Numeric 9 STATE Cardholder s state. No Alpha 2 SWIPE Allows Track 1 and Track 2 data to be passed to enable a card-present transaction. No Alphanumeric 80 TAXAMT Tax Amount The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators ( not 1,234.56). See FDMS South Currency Codes and Decimal Positions on page 153. No (but provides best rate when used) Currency 10 If a purchase is exempted from tax, then you must send TAXEXEMPT=Y&TAXAMT=0.00. TAXEXEMPT Is the customer tax exempt? Y or N If a purchase is exempted from tax, then you must send TAXEXEMPT=Y&TAXAMT=0.00. No Alpha 1 Purchase Card Line Item Parameters, FDMS South Line item data 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 VeriSign, Inc /Rev

118 VeriSign Payment Services Payflow Pro Developer s Guide 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. Table D-7 Purchase card line item parameters Parameter Description Required Type Length L_QTYn Quantity (whole units only) Yes Numeric 10 L_COMMCODEn Item commodity code No Alphanumeric L_DESCn Item description No Alphanumeric L_UOMn Item unit of measure. See Units of Measure on page 147. No Alpha 3 L_COSTn Cost per item, excluding tax No Currency 10 L_PRODCODEn Supplier specific product code No Alphanumeric 12 L_DISCOUNTn Discount per line item No Currency 10 L_AMTn Total line item amount including tax and discount. + for debit, - for credits Yes Currency 10 L_TAXAMTn Line item Tax amount No Currency 10 FDMS South Purchase Card Level 2 and 3 Example Parameter List TRXTYPE=S&TENDER=C&PARTNER=VeriSign&VENDOR=SuperMerchant&USER =SuperMerchant&PWD=x1y2z3&STATE=CA&FIRSTNAME=John&LASTNAME=Smit h&city=redwood&countrycode=usa&custcode=12345&discount=.25&d UTYAMT=34.00&FREIGHTAMT=12.00&INVNUM= &ORDERDATE= &PONUM= &SHIPFROMZIP= &SHIPTOZI P=94065&TAXAMT=1.00&TAXEXEMPT=Y FDMS South Line Item Parameter Example TRXTYPE=S&TENDER=C&PARTNER=VeriSign&VENDOR=SuperMerchant&USER =SuperMerchant&PWD=x1y2z3&STATE=CA&FIRSTNAME=John&LASTNAME=Smit h&city=redwood&countrycode=usa&custcode=12345&discount=.25&d UTYAMT=34.00&FREIGHTAMT=12.00&INVNUM= &ORDERDATE= &PONUM= &SHIPFROMZIP= &SHIPTOZI P=94065&TAXAMT=1.00&TAXEXEMPT=Y&L_QTY1=1&L_UPC1=PN&L_DESC1=Te 106 VeriSign, Inc /Rev. 3

119 Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions st&l_uom1=inq&l_cost1=1.00&l_prodcode1=12345&l_discount1=.25&&l _AMT1=.75&L_TAXAMT1=0 Performing Purchasing Card Transactions, Global Payments - Central Global Payments - Central (MAPP) supports Level 2 for MasterCard, and Visa Sale, Credit, and Delayed Capture transactions. Global Payments - Central Level 2 Parameters Both Level 2 values listed in Table D-9 are required to get the discount rate. You must pass the following parameters. Table D-8 Required Level 2 parameters for Global Payments - Central Data Items Mandatory / Optional Payflow Pro Parameter Format (min/max, type) Customer Code M CUSTCODE 1/16, char Sales Tax M TAXAMT The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators ( not 1,234.56). N Example Global Payments - Central Level 2 Visa or MasterCard Transaction Parameter List "TRXTYPE=S&ACCT= &AMT=20.10&CITY=Mountain View&COMMENT1=L2 Testing&EXPDATE=1209&NAME=Cardholder Name&PARTNER=VeriSign&PWD=pwd&STATE=CA&STREET=123 Main St.&TENDER=C&USER=user&ZIP=94043&CUSTCODE=123456&TAXAMT=1.34" Performing Purchasing Card Transactions, Global Payments - East Global Payments - East (NDCE) supports Level 2 for American Express, MasterCard, and Visa. VeriSign, Inc /Rev

120 VeriSign Payment Services Payflow Pro Developer s Guide Global Payments - East Level 2 Parameters Both Level 2 values listed in Table D-9 are required to get the discount rate. You must pass the following parameters in Authorization and Sale transactions. Table D-9 Required Level 2 parameters for Global Payments - East Data Items Payflow Pro Parameter Required? Type Length (min/ max) Customer Code CUSTCODE Yes char 1/16 Sales Tax TAXAMT Yes numeric The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators ( not 1,234.56). Example Global Payments - East Level 2 Visa or MasterCard Transaction Parameter List "TRXTYPE=S&ACCT= &AMT=20.10&CITY=Mountain View&COMMENT1=L2 Testing&EXPDATE=1209&NAME=Cardholder Name&PARTNER=VeriSign&PWD=pwd&STATE=CA&STREET=123 Main St.&TENDER=C&USER=user&ZIP=94043&CUSTCODE=123456&TAXAMT=1.34" Performing Purchasing Card Transactions, Nova Nova supports Level 2 for Visa or MasterCard Sale, Credit, or Delayed Capture transactions. 108 VeriSign, Inc /Rev. 3

121 Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions Nova Level 2 Parameters Both Level 2 values listed in Table D-9 are required to get the discount rate. You must pass the following parameters in Authorization and Sale transactions. Table D-10 Required Level 2 parameters for Nova Data Items Mandatory / Optional Payflow Pro Parameter Format (min/max, type) Customer Code M CUSTCODE Value of {ServerID}{TransID} is sent if no value is provided. 1/16, char Sales Tax M TAXAMT Value of 0 (zero) is sent if no value is provided. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators ( not 1,234.56). If a purchase is exempted from tax, then you must send TAXEXEMPT=Y&TAXAMT=0.00. N Additional Parameters, Nova The following parameters are recommended to obtain the best rates for purchasing card transactions with Nova: Table D-11 Purchasing card parameters, Nova Parameter Description Required Type Length COMMCARD One-character value representing the type of commercial card. P Purchase Card C Corporate Card B Business Card U Unknown (default) N None No (defaults to U - Unknown) Alphanu meric 1 PONUM Purchase Order Number No (when used provides best rate) Alphanu meric 25 VeriSign, Inc /Rev

122 VeriSign Payment Services Payflow Pro Developer s Guide Table D-11 Purchasing card parameters, Nova Parameter Description Required Type Length TAXAMT Tax Amount The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators ( not 1,234.56). No (when used provides best rate) Currenc y 10 If a purchase is exempted from tax, then you must send TAXEXEMPT=Y&TAXAMT=0.00. Example Nova Level 2 Transaction Parameter List "TRXTYPE=S&ACCT= &AMT=20.10&CITY=Mountain View&COMMENT1=L2 Testing&EXPDATE=1209&NAME=Cardholder Name&PARTNER=VeriSign&PWD=pwd&STATE=CA&STREET=123 Main St.&TENDER=C&USER=user&ZIP=94043&CUSTCODE=123456&TAXAMT=1.34" Performing Level 2 Purchasing Card Transactions, Paymentech Paymentech supports Level 2 for American Express, MasterCard, and Visa. Paymentech Level 2 Parameters Both Level 2 values listed in Table D-12 are required to get the discount rate. Table D-12 Required Level 2 parameters for Paymentech Paymentech Data Items Mandatory / Optional Payflow Pro Parameter Format (min/max, type) Customer Ref No M PONUM 1/17, char Sales Tax M TAXAMT The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators ( not 1,234.56). N 110 VeriSign, Inc /Rev. 3

123 Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions Example Paymentech Level 2 Transactions Example Paymentech Level 2 Visa and MasterCard Transaction Parameter List "TRXTYPE=S&TENDER=C&PARTNER=Partner&PWD=Password&USER=User&ACCT = &EXPDATE=1203&AMT=1.00&COMMENT1=0508&NAME=Robert &STREET=1600&ZIP=94065&CVV2=426&PONUM=ABCDEFGHIJ&TAXAMT=1.00" "TRXTYPE=S&TENDER=C&PARTNER=Partner&PWD=Password&USER=User&ACCT = &EXPDATE=1203&AMT=1.00&COMMENT1=0508&STREET=160 0&ZIP=94065&CVV2=426&PONUM=ABCDEFGHIJ&TAXAMT=1.00" Example American Express Level 2 Transaction Parameter List "TRXTYPE=S&TENDER=C&PARTNER=Partner&PWD=Password&USER=User&ACCT = &EXPDATE=1203&AMT=1.00&COMMENT1=0508&NAME=Robert& STREET=1600&ZIP=94065&DESC=Descriptor&DESC1=Descriptor1&DESC2=Descript or2&desc3=descriptor3&desc4=descriptor4" Performing Level 2 Purchasing Card Transactions, Vital Vital supports MasterCard and Visa for Level 2. Vital indicates in the authorization response whether or not the credit card in the transaction is a commercial card. Based in the commercial card indicator, VeriSign will format the Level 2 information in the settlement request. Vital Level 2 Transaction Data Level 2 values marked as mandatory in Table D-13 are required to get the discount rate. Table D-13 Vital Level 2 parameters Vital Name Mandatory / Optional Payflow Pro Parameter Format (min/max, type) Invoice # / Cust Ref ID M INVNUM 1/20, A/N Tax Amount M TAXAMT. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators ( not 1,234.56). If a purchase is exempted from local tax, then you must send TAXEXEMPT=Y&TAXAMT=0.00. NUM VeriSign, Inc /Rev

124 VeriSign Payment Services Payflow Pro Developer s Guide Table D-13 Vital Level 2 parameters Tax Amount Identifier O TAXEXEMPT, Y or N If a purchase is exempted from local tax, then you must send TAXEXEMPT=Y&TAXAMT= , A Example Vital Level 2 Visa Transaction Parameter List "TRXTYPE=S&ACCT= &AMT=20.02&CITY=Mountain View&COMMENT1=L2 Testing&EXPDATE=1209&INVNUM= &NAME=CardHolder Name&PARTNER=verisign&PWD=pwd&STATE=CA&STREET=123 Main St.&TAXAMT=1.01&TAXEXEMPT=N&TENDER=C&USER=user&ZIP=94043" Performing Level 3 Purchasing Card Transactions, Paymentech Paymentech supports Level 3 for MasterCard and Visa. Both Level 2 transaction parameters are required for Level 3 transactions. Level 3 transactions that do not include the Level 2 values are rejected. Paymentech Level 2 Transaction Data (Required for Level 3) Both Level 2 values listed in Table D-14 are required to get the discount rate. Table D-14 Required Paymentech Level 2 parameters Paymentech Data Items Mandatory / Optional Payflow Pro Parameter Format (min/max, type) Customer Ref No M PONUM 1/17, char Sales Tax M TAXAMT The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators ( not 1,234.56). NUM Paymentech Level 3 MasterCard Transaction Data Table D-15 Paymentech Level 3 MasterCard order and line-item parameters Paymentech MasterCard data item Mandatory / Optional Payflow Pro Parameter Format (min/max, type) 112 VeriSign, Inc /Rev. 3

125 Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions Table D-15 Paymentech Level 3 MasterCard order and line-item parameters Order Freight Amt M FREIGHTAMT NUM Duty Amt M DUTYAMT NUM Destination ZIP M SHIPTOZIP Destination Country M COUNTRYCODE Ship from ZIP M SHIPPEDFROMZIP Discount Amount M DISCOUNT NUM Alternate Tax ID M ALTERNATETAXID Alternate Tax Amt M ALNTERNATETAXAMT NUM Line Item Record #1 Description M L_DESCn Product Code O L_PRODCODEn Quantity M L_QTYn NUM Unit of measure M L_UOMn Tax Amt O TAXAMTn NUM Tax Rate O TAXPERCENTAGEn Line Item Record #2 Line-item Total O L_AMTn NUM Discount Amt O L_DISCOUNTn NUM Tax Type Applied O L_TAXTYPEn VeriSign, Inc /Rev

126 VeriSign Payment Services Payflow Pro Developer s Guide Paymentech Level 3 Visa Transaction Data Level 3 transactions should include at least one line item. Table D-16 Paymentech Level 3 Visa order and line-item parameters Paymentech Visa data item Mandatory / Optional Payflow Pro Parameter Format (min/max, type) Order Freight Amt M FREIGHTAMT NUM Duty Amt M DUTYAMT NUM Destination ZIP M SHIPTOZIP Destination Country M COUNTRYCODE Ship from ZIP M SHIPPEDFROMZIP Discount Amount M DISCOUNT NUM VAT/Tax Amt M TAXAMT NUM VAT/Tax Rate M TAXPERCENTAGE Line Item Record #1 Description M L_DESCn Product Code O L_PRODCODEn Quantity M L_QTYn NUM Unit of measure M L_UNITn (?) Tax Amt O L_TAXAMTn NUM Tax Rate O L_TAXRATEn Line Item Record #2 Line-item Total O L_AMTn NUM Discount Amt O L_DISCOUNTn NUM Item commodity code O L_UPCn Unit cost M L_COSTn NUM 114 VeriSign, Inc /Rev. 3

127 Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions Example Paymentech Level 3 Transaction Parameter Lists Example Paymentech Level 3 MasterCard Transaction "TRXTYPE=S&TENDER=C&PARTNER=Partner&PWD=Password&USER=User&ACCT = &EXPDATE=1203&AMT=1.00&COMMENT1=0508&NAME=Robert &STREET=1600&ZIP=94065&CVV2=426&PONUM=ABCDEFGHIJ&TAXAMT=1.00&FR EIGHTAMT=2.00&DUTYAMT=3.00&SHIPTOZIP=94543&COUNTRYCODE=840&SHIPF ROMZIP=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_AMT 1=6&L_DISCOUNT1=7&L_TAXTYPE1=8" Example Paymentech Level 3 Visa Transaction "TRXTYPE=S&TENDER=C&PARTNER=Partner&PWD=Password&USER=User&ACCT = &EXPDATE=1203&AMT=1.00&COMMENT1=0508&NAME=Robert &STREET=1600&ZIP=94065&CVV2=426&PONUM=ABCDEFGHIJ&TAXAMT=1.00&FR EIGHTAMT=2.00&DUTYAMT=3.00&SHIPTOZIP=94543&COUNTRYCODE=840&SHIPF ROMZIP=94509&DISCOUNT=4.00&VATAXAMT=5.00&VATAXPERCENT=10&L_DESC 1=Vital Pcard&L_UPC1=1&L_UOM1=2&L_QTY1=3&L_TAXAMT1=4&L_TAXRATE1=5& L_AMT1=6&L_DISCOUNT1=7&L_COMMCODE1=8&L_COST1=9&L_COST1=10" Performing Level 3 MasterCard Transactions, Vital 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 mandatory are required for Level 3 transactions. Level 3 transactions that do not include the mandatory Level 2 values are rejected. IMPORTANT! The values required for Level 3 status vary by bank, so contact your bank for details. Vital Level 2 MasterCard Transaction Data for Line-Item Transactions (Required for Level 3) Table D-17 Vital Level 2 MasterCard transaction data for line-item transactions Vital Name Mandatory / Optional Payflow Pro Parameter Length, Data Type Total Authorization Amount M AMT 12, NUM VeriSign, Inc /Rev

128 VeriSign Payment Services Payflow Pro Developer s Guide Table D-17 Vital Level 2 MasterCard transaction data for line-item transactions Purchase Identifier Format Code M PONUM Value of TransID is sent if no value is provided. 25, A/N Tax Amt M TAXAMT The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators ( not 1,234.56). If a purchase is exempted from tax, then you must send TAXEXEMPT=Y&TAXAMT=0.00. NUM Lcl Tax O LOCALTAXAMT 12, NUM Lcl Tax Incl Flag O TAXEXEMPT, Y or N. If a purchase is exempted from tax, then you must send TAXEXEMPT=Y&TAXAMT=0.00. National Tax Amt O NATIONALTAXAMT You may omit this parameter if there is no such tax. 1, A/N 12, NUM Purch Ord #/Cust Ref ID M INVNUM Value of TransID is sent if no value is provided. 20, A/N 116 VeriSign, Inc /Rev. 3

129 Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions Vital Level 3 MasterCard Extended Data The parameters listed in Table D-18 apply to Level 3 MasterCard transactions as extended data. Table D-18 Vital Level 3 MasterCard Extended Data Vital Name Mandatory / Optional Payflow Pro Parameter Length, Data Type Freight Amt O FREIGHTAMT 12, NUM Duty Amt O DUTYAMT 12, NUM Dest Postal / ZIP Code M SHIPTOZIP The ZIP code of the address to which the goods are shipped. 10, A/N Ship from Postal / ZIP Code M SHIPFROMZIP The postal code (called ZIP code in the USA) from which shipping occurs. 10, A/N Dest Country Code O COUNTRYCODE 3, A/N Alt Tax Amt O ALTTAXAMT 9, NUM VeriSign, Inc /Rev

130 VeriSign Payment Services Payflow Pro Developer s Guide Vital Level 3 MasterCard Line-item Detail Records Table D-19 Vital Level 3 MasterCard line-item detail record Vital Name Mandatory / Optional Payflow Pro Parameter Length, Data Type 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_QUANTITY<n>) and unit price (L_COST<n>) fields. Item Descriptor M L_DESCn 35, A/N Product Code O L_UPCn 12, A/N Quantity M L_QTYn 12, NUM Unit of Measure/Code M L_UOMn 12, A/N Tax Rate Applied O L_TAXRATEn 4, NUM Tax Type Applied O L_TAXTYPEn 4, A/N Tax Amount O L_TAXAMTn 12, NUM Discount Amount O L_DISCOUNTn 12, NUM Example Vital Level 3 MasterCard Transaction Parameter List "TRXTYPE=S&TENDER=C&PARTNER=Partner&USER=User&PWD=Password&ACCT = &EXPDATE=0406&AMT=1.00&STREET=5199 JOHNSON&ZIP=94588&ALTTAXAMT=1.00&CUSTVATREGNUM=11111&LOCALTAXA MT=1.00&NATIONALTAXAMT=1.00&COMMCODE=22222&VATAXAMT=1.00&VATAX PERCENT=10&TAXEXEMPT=Y&DISCOUNT=1.00&FREIGHTAMT=1.00&DUTYAMT=1.00&SHIPTOZIP=33333&SHIPFROMZIP=44444&COUNTRYCODE=840&ORDERDATE =020725&L_COMMCODE1= ABC&L_DESC1=Line item 1 description&l_upc1=cba &l_qty1=1&l_uom1= &l_cost 1=1.00&L_TAXAMT1=1.00&L_TAXRATE1=1.00&L_DISCOUNT1=1.00&L_AMT1=1.00& L_TAXTYPE1=TT3" Performing Level 3 Visa Transactions, Vital 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 mandatory are required for Level 3 transactions. Level 3 transactions that do not include the mandatory Level 2 values are rejected. 118 VeriSign, Inc /Rev. 3

131 Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions IMPORTANT! The values required for Level 3 status vary by bank, so contact your bank for details. VeriSign, Inc /Rev

132 VeriSign Payment Services Payflow Pro Developer s Guide Vital Level 2 Visa Transaction Data for Line-Item Transactions (Required for Level 3) Table D-20 Vital Level 2 Visa transaction data for line-item transactions Vital Name Mandatory / Optional Payflow Pro Parameter Length, Data Type Total Authorization Amount M AMT 12, NUM Purchase Identifier Format Code M PONUM Value of TransID is sent if no value is provided. 25, A/N Tax amount M TAXAMT The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators ( not 1,234.56). If a purchase is exempted from tax, then you must send TAXEXEMPT=Y&TAXAMT=0.00. NUM Lcl Tax O LOCALTAXAMT 12, NUM Lcl Tax Incl Flag TAXEXEMPT, Y or N. If a purchase is exempted from tax, then you must send TAXEXEMPT=Y&TAXAMT= , A/N National Tax Amt O NATIONALTAXAMT 12, NUM Purch Ord #/Cust Ref ID M INVNUM] Value of TransID is sent if no value is provided. 20, A/N Vital Level 3 Visa Extended Data The parameters listed in Table D-21 apply to Level 3 Visa transactions as extended data. Table D-21 Vital Level 3 Visa extended data Vital Name Mandatory / Optional Payflow Pro Parameter Length, Data Type 120 VeriSign, Inc /Rev. 3

133 Appendix D Submitting Purchasing Card Level 2 and Level 3 Transactions Table D-21 Vital Level 3 Visa extended data (Continued) Summary Commodity Code M COMMCODE Commodity code identifier for the business. 4, A/N Discount Amt O DISCOUNT 12, NUM Freight Amt O FREIGHTAMT 12, NUM Duty Amt O DUTYAMT 12, NUM Order Date O ORDERDATE Format is mmddyy with no slashes or dashes. For example, July 28, 2003 is Dest Postal / ZIP Code M SHIPTOZIP The ZIP code of the address to which the goods are shipped. 6, NUM 10, A/N Ship from Postal / ZIP Code M SHIPFROMZIP The postal code (called ZIP code in the USA) from which shipping occurs. 10, A/N Dest Country Code O COUNTRYCODE 3, A/N VAT Registration Number M VATREGNUM Can be part of the registration data or passed with each transaction. 20, A/N Unique VAT Inv Ref # M INVNUM Can be part of the registration data or passed with each transaction. 20, A/N Cust VAT Registr # M CUSTVATREGNUM 13, A/N VAT/Tax Amt (Freight/Ship) VAT/Tax Rate (Freight/Ship) O VATTAXAMT 12, NUM O VATTAXPERCENT 4, NUM VeriSign, Inc /Rev

134 VeriSign Payment Services Payflow Pro Developer s Guide Vital Level 3 Visa Line-item Detail Records Table D-22 Vital Level 3 Visa line-item detail record Vital Name Mandatory / Optional Payflow Pro Parameter Length, Data Type 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_QUANTITY<n>) and unit price (L_COST<n>) fields. Item Commodity Code O L_COMMCODEn 12, A/N Item Descriptor M L_DESCn 35, A/N Product Code O L_UPCn 12, A/N Quantity M L_QTYn 12, NUM Unit of Measure/Code M L_UOMn 12, A/N Unit Cost M L_COSTn 12, NUM VAT/Tax Amount O L_TAXAMTn 12, NUM VAT/Tax Rate O L_TAXRATEn 4, NUM Discount Per Line Item O L_DISCOUNTn 12, NUM Line-item Total O L_AMTn 12, NUM Example Vital Level 3 Visa Transaction Parameter List "TRXTYPE=S&TENDER=C&PARTNER=Partner&USER=User&PWD=Password&ACCT = &EXPDATE=0406&AMT=1.00&STREET=5199 JOHNSON&TAXAMT=106&ZIP=94588&ALTTAXAMT=1.00&CUSTVATREGNUM=1111 1&LOCALTAXAMT=1.01&NATIONALTAXAMT=1.02&COMMCODE=22222&VATAXAM T=1.03&VATAXPERCENT=55&TAXEXEMPT=N&DISCOUNT=.50&FREIGHTAMT=1.00 &DUTYAMT=1.00&SHIPTOZIP=33333&SHIPFROMZIP=44444&COUNTRYCODE=840 &ORDERDATE=020725&L_COMMCODE1= ABC&L_DESC1=Line item 1 description&l_upc1=cba &l_qty1=1&l_uom1= &l_cost 1=1.50&L_TAXAMT1=1.05&L_TAXRATE1=12&L_DISCOUNT1=.50&L_AMT1=1.00&L_ TAXTYPE1=TT1" 122 VeriSign, Inc /Rev. 3

135 xi Apend APPENDIX E EAdditional Reporting Parameters This appendix lists parameters whose values can appear in VeriSign Manager reports. For example, the Shipping and Billing report displays these values. Some of the following parameters may also have other purposes. The STREET and ZIP parameters, for instance, are also used for AVS. Note For regular credit card transactions, reporting parameters are normally not passed to the processor. See Appendix A, Processors Requiring Additional Transaction Parameters to learn which fields are sent to your processor. Table E-1 VeriSign reporting parameters Parameter Description Required Type Max Length CITY Cardholder s billing city No Alpha 20 COMMENT1 User-defined value for reporting and auditing purposes (VeriSign parameter only) No Alphanumeric 128 COMMENT2 User-defined value for reporting and auditing purposes (Verisign parameter only) No Alphanumeric 128 COMPANYNAME Cardholder s company No Alphanumeric COUNTRY Cardholder s billing country code No Alphanumeric CUSTCODE Customer code No Alphanumeric DUTYAMT Duty amount No Alphanumeric VeriSign, Inc /Rev

136 VeriSign Payment Services Payflow Pro Developer s Guide Table E-1 VeriSign reporting parameters (Continued) Parameter Description Required Type Max Length Cardholder s address No Alphanumeric 64 FIRSTNAME Cardholder s first name No Alpha 15 FREIGHTAMT Freight amount No Currency 10 LASTNAME Cardholder s last name No Alpha 15 NAME Cardholder s name No Alphanumeric PONUM Purchase Order Number No Alphanumeric SHIPTOCITY Shipping city No Alphanumeric SHIPTOFIRSTNAME First name in the shipping address No Alphanumeric SHIPTOLASTNAME Last name in the shipping address No Alphanumeric SHIPTOSTATE Shipping state. US = 2-letter state code. Outside US, use full name. No Alphanumeric 10 SHIPTOSTREET Shipping street address No Alphanumeric 30 SHIPTOZIP Shipping postal code (called ZIP code in the USA) No Alphanumeric 9 STATE Cardholder s billing state code No Alphanumeric 2 STREET Cardholder s billing street address (used for AVS and reporting) No Alphanumeric 30 TAXAMT Tax amount No Currency VeriSign, Inc /Rev. 3

137 Appendix E Additional Reporting Parameters Table E-1 VeriSign reporting parameters (Continued) Parameter Description Required Type Max Length ZIP Account holder s 5- to 9-digit postal code (called ZIP code in the USA). Do not use spaces, dashes, or non-numeric characters. The postal code is verified by the AVS service. No Numeric 9 VeriSign, Inc /Rev

138 VeriSign Payment Services Payflow Pro Developer s Guide 126 VeriSign, Inc /Rev. 3

139 xi Apend APPENDIX F FXMLPay About XMLPay XMLPay specifies an XML syntax for payment requests and associated responses in a payment-processing network. Instead of using name/value pairs, Payflow Pro allows for the use of XML documents via XMLPay. The typical user of XMLPay is an Internet merchant or merchant aggregator who wants to dispatch credit card, corporate purchase card, Automated Clearinghouse (ACH), or other payment requests to a financial processing network. Using the data type definitions specified by XMLPay, such a user creates a client payment request and dispatches it in the same fashion as using name/value pairs to an associated XMLPay-compliant server component. Responses are also formatted in XML and convey the results of the payment requests to the client. XMLPay 2.0 Core Specification Document VeriSign XMLPay 2.0 Core Specification defines an XML syntax for payment transaction requests, responses, and receipts in a payment processing network. You may obtain a copy of this document from the Downloads page of VeriSign Manager ( Note For specific examples of how to submit XML documents using the Payflow Pro client API, see the Payflow Pro SDK Download package. VeriSign, Inc /Rev

140 VeriSign Payment Services Payflow Pro Developer s Guide 128 VeriSign, Inc /Rev. 3

141 xi Apend APPENDIX G GISO Country Codes The following International Standards Organization (ISO) country codes are used when filling the order fields COUNTRY, COUNTRYCODE, and CORPCOUNTRY: Table G-1 ISO Country Codes Country Name Code Country Name Code Afghanistan 4 Bangladesh 50 Albania 8 Barbados 52 Algeria 12 Belarus 112 American Samoa 16 Belgium 56 Andorra 20 Belize 84 Angola 24 Benin 204 Anguilla 660 Bermuda 60 Antarctica 10 Bhutan 64 Antigua and Barbuda 28 Bolivia 68 Argentina 32 Bosnia-Herzegovina 70 Armenia 51 Botswana 72 Aruba 533 Bouvet Island 74 Australia 36 Brazil 76 Austria 40 British Indian Ocean Territory 86 Azerbaijan 31 Brunei Darussalam 96 Bahamas 44 Bulgaria 100 Bahrain 48 Burkina Faso 854 VeriSign, Inc /Rev

142 Payflow Pro Developer s Guide -- Table G-1 ISO Country Codes Country Name Code Country Name Code Burundi 108 Dominican Republic 214 Cambodia 116 East Timor 626 Cameroon 120 Ecuador 218 Canada 124 Egypt 818 Cape Verde 132 El Salvador 222 Cayman Islands 136 Equatorial Guinea 226 Central African Republic 140 Eritrea 232 Chad 148 Estonia 233 Chile 152 Ethiopia 231 China 156 Falkland Islands (Malvinas) 238 Christmas Island 162 Faroe Islands 234 Cocos (Keeling) Islands 166 Fiji 242 Colombia 170 Finland 246 Comoros 174 France 250 Congo 178 France, Metropolitan 249 Cook Islands 184 French Guiana 254 Costa Rica 188 French Polynesia 258 Cote D ivoire (formerly Ivory Coast) 384 French Southern Territories 260 Croatia (local name: Hrvatska) 191 Gabon 266 Cuba 192 Gambia 270 Cyprus 196 Georgia 268 Czech Republic 203 Germany 276 Denmark 208 Ghana 288 Djibouti 262 Gibraltar 292 Dominica 212 Greece VeriSign, Inc.

143 Payflow Pro Developer s Guide -- Table G-1 ISO Country Codes Country Name Code Country Name Code Greenland 304 Jordan 400 Grenada 308 Kazakhstan 398 Guadeloupe 312 Kenya 404 Guam 316 Kiribati 296 Guatemala 320 Korea, Democratic People s Republic of (formerly North Korea) Guinea 324 Korea, Republic of (formerly South Korea) Guinea-Bissau 624 Kuwait 414 Guyana 328 Kyrgyzstan 417 Haiti 332 Lao People s Democratic Republic (formerly Laos) 418 Heard and McDonald Islands 334 Latvia 428 Honduras 340 Lebanon 422 Hong Kong 344 Lesotho 426 Hungary 348 Liberia 430 Iceland 352 Libyan Arab Jamahiriya (formerly Libya) 434 India 356 Liechtenstein 438 Indonesia 360 Lithuania 440 Iran (Islamic Republic of) 364 Luxembourg 442 Iraq 368 Macau 446 Ireland 372 Macedonia, the Former Yugoslav Republic of 807 Israel 376 Madagascar 450 Italy 380 Malawi 454 Jamaica 388 Malaysia 458 Japan 392 Maldives VeriSign, Inc.

144 Payflow Pro Developer s Guide -- Table G-1 ISO Country Codes Country Name Code Country Name Code Mali 466 Niue 570 Malta 470 Norfolk Island 574 Marshall Islands 584 Northern Mariana Islands 580 Martinique 474 Norway 578 Mauritania 478 Oman 512 Mauritius 480 Pakistan 586 Mayotte 175 Palau 585 Mexico 484 Panama 591 Micronesia, Federated States of 583 Papua New Guinea 598 Moldova, Republic of 498 Paraguay 600 Monaco 492 Peru 604 Mongolia 496 Philippines 608 Montserrat 500 Pitcairn 612 Morocco 504 Poland 616 Mozambique 508 Portugal 620 Myanmar (formerly Burma) 104 Puerto Rico 630 Namibia 516 Qatar 634 Nauru 520 Reunion 638 Nepal 524 Romania 642 Netherlands 528 Russian Federation 643 Netherlands Antilles 530 Rwanda 646 New Caledonia 540 Saint Kitts and Nevis 659 New Zealand 554 Saint Lucia 662 Nicaragua 558 Saint Vincent and the Grenadines 670 Niger 562 Samoa 882 Nigeria 566 San Marino VeriSign, Inc.

145 Payflow Pro Developer s Guide -- Table G-1 ISO Country Codes Country Name Code Country Name Code Sao Tome and Principe 678 Tajikistan 762 Saudi Arabia 682 Tanzania, United Republic of 834 Senegal 686 Thailand 764 Seychelles 690 Togo 768 Sierra Leona 694 Tokelau 772 Singapore 702 Tonga 776 Slovakia (Slovak Republic) 703 Trinidad and Tobago 780 Slovenia 705 Tunisia 788 Solomon Islands 90 Turkey 792 Somalia 706 Turkmenistan 795 South Africa 710 Turks and Caicos Islands 796 South Georgia and the South Sandwich Islands 239 Tuvalu 798 Spain 724 Uganda 800 Sri Lanka 144 Ukraine 804 St. Helena 654 United Arab Emirates 784 St. Pierre and Miquelon 666 United Kingdom 826 Sudan 736 United States 840 Suriname 740 United States Minor Outlying Islands 581 Svalbard and Jan Mayen Islands 744 Uruguay 858 Swaziland 748 Uzbekistan 860 Sweden 752 Vanuatu 548 Switzerland 756 Vatican City State 336 Syrian Arab Republic (formerly Syria) 760 Venezuela 862 Taiwan, Province of China 158 Viet Nam VeriSign, Inc.

146 Payflow Pro Developer s Guide -- Table G-1 ISO Country Codes Country Name Code Country Name Code Virgin Islands (British) 92 Western Samoa 882 Virgin Islands (U.S.) 850 Yemen 887 Wallis and Futuna Islands 876 Yugoslavia 891 Virgin Islands (British) 92 Zaire 180 Virgin Islands (U.S.) 850 Zambia 894 Western Sahara 732 Zimbabwe VeriSign, Inc.

147 Appendix G ISO Country Codes VeriSign, Inc /Rev

148 VeriSign Payment Services Payflow Pro Developer s Guide 136 VeriSign, Inc /Rev. 3

149 xi Apend APPENDIX H HCodes Used by FDMS South Only Codes used by FDMS South only are Country Codes, Units of Measure, and Currency Codes. MasterCard Country Codes Table H-1 MasterCard Country Codes ALBANIA ALGERIA AMERICAN SAMOA ANDORRA ANGOLA ANGUILLA ANTARCTICA ANTIGUA AO PEOPLES DEMOCRATIC APHGANISTAN ARGENTINA ARMENIA ARUBA AUSTRALIA AUSTRIA AZERBAIJAN ALB DZA ASM AND AGO AIA ATA ATG LAO AFG ARG ARN ABW AUS AUT AZE VeriSign, Inc /Rev DRAFT

150 Payflow Pro Developer s Guide -- Table H-1 MasterCard Country Codes Table H-1 MasterCard Country Codes BAHAMAS BHS CHAD TCD BAHRAIN BHR CHILE CHL BANGLADESH BGD CHINA CHN BARBADOS BELARUS BELGIUM BRB BLR BEL CHRISTMAS ISLAND CMEROON, UNITED REP. CXR CMR BELIZE BENIN BERMUDA BHUTAN BOLIVIA BOSNIA AND HERZIGOVINA BLZ BEN BMU BTN BOL BIH COCOS (KEELING) ISLAND COLUMBIA COMOROS CONGO COOK ISLANDS COSTA RICA CCK COL COM GOG COK CRI BOTSWANA BWA COTED'IVOIRE CIV BOUVET ISLAND BVT CROATIA HRV BRAZIL BRA CYPRUS CYP BRITISH INDIAN OCEAN TERRITORY BRUNEI BULGARIA BURKINA FASO BURUNDI IOT BRN BGR BFA BDI CZECH REPUBLIC DENMARK DJIBOUTI DOMINICA DOMINICAN REPUBLIC CZE DNK DJI DMA DOM CAMBODIA KHM EL SALVADOR SLV CANADA CAPE VERDE CAYMAN ISLANDS CENTRAL AFRICAN REPUBLIC CAN CPV CYM CAF EQUATORIAL GUINEA ESTONIA ETHIOPIA FAEROE ISLANDS GNQ EST ETH FRO 138 DRAFT VeriSign, Inc.

151 Payflow Pro Developer s Guide -- Table H-1 MasterCard Country Codes Table H-1 MasterCard Country Codes FALKLAND ISLANDS (MALVINAS) FIJI FLK FJI HAITI HEARD & MCDONALDS ISLAND HTI HMD FINLAND FIN HONDURAS HND FRANCE FRA HONG KONG HKG FRENCH GUIANA GUF HUNGARY HUN FRENCH POLYNESIA FRENCH SOUTHERN TERRITORY GABON GAMBIA GEORGIA GERMAN DEMOCRATIC REP GERMANY GHANA GIBRALTER GRECE GREENLAND GRENADA GUADALUPE GUAM GUATEMALA GUINEA GUINEA-BISSAU GUYANA PYF ATF GAB GMB GEO DDR DEU GHA GIB GRC GRL GRD GLP GUM GTM GIN GNB GUY ICELAND INDIA INDONESIA IRAN IRAQ IRELAND ISRAEL ITALY JAMAICA JAPAN JORDAN KAZAKHSTAN KENYA KOREA, REPUBLIC OF KUWAIT KYRGYZSTAN LATVIA LEBANON LESOTHO LIBERIA ISL IND IDN IRN IRQ IRL ISR ITA JAM JPN JOR KAZ KEN KOR KWT KGZ LVA LBN LSO LBR 139 DRAFT VeriSign, Inc.

152 Payflow Pro Developer s Guide -- Table H-1 MasterCard Country Codes Table H-1 MasterCard Country Codes LIBYAN ARAB JAMAHIRIYA LIECHTNSTIEN LITHUANIA LBY LIE LTU NEPAL NETHERLANDS NETHERLANDS ANTILLES NPL NLD ANT LUXEMBOURG LUX NEW CALDONIA NCL MACAU MAC NEW ZEALAND NZL MALAYSIA MYS NICARAGUA NIC MALDIVES MDV NIGER NER MALI MLI NIGERIA NGA MALTA MLT NIUE NIU MANACO MCO NORFOLK ISLAND NFK MARSHALL ISLANDS MHL NORTHERN MARIANA ISLAND MNP MATINIQUE MTQ NORWAY NOR MAURITANIA MRT OMAN OMN MAURITIUS MUS PAKISTAN PAK MEXICO MEX PALAU PLW MICRONESIA FSM PANAMA PAN MOLDOVA MONGOLIA MONTSERRAT MOROCCO MOZAMBIQUE MYANMAR NAMIBIA NAURU NEGEL MDA MNG MSR MAR MOZ MMR NAM NRU SEN PAPAU NEW GUINEA PARAGUAY PERU PHILIPPINES PITCAIRN ISLAND POLAND PORTUGUL PUERTO RICO QATAR PNG PRY PER PHI PCN POL PRT PRI QAT 140 DRAFT VeriSign, Inc.

153 Payflow Pro Developer s Guide -- Table H-1 MasterCard Country Codes Table H-1 MasterCard Country Codes REUNION ROMANIA RUSSIAN FERERATION REU ROM RUS SYRIAN ARAB REPUBLIC TAIWAN, PROVIDENCE OF CHINA SYR TWN RWANDA RWA TAJIKISTAN TJK SAMOA SAN MARINO SAN TOME AND PRICIPEL WSM SMR STP TANZANIA, UNITED REPUBLIC THAILAND TOGO TZA THA TGO SAUDI ARABIA SAU TOKELAU TKL SEYCHELLES SYC TONGA TON SIERRA LEONE SINGAPORE ST. HELENA ST. KITTS-NEVIS-ANGU ILLA ST. LUCIA SLE SGP SHN KNA LCA TRINIDAD AND TOBAGO TUNISIA TURKEY TURKMENISTAN TURKS & CAICOS ISLANDS TTO TUN TR TM TC ST. PIERRE AND MIQUELON ST. VINCENT AND THE GRENADINES SUDAN SURINAM SVALBARD & JAN MAYEN IS. SWAZILAND SWEDEN SWITZERLAND SPM VCT SDN SUR SJM SWZ SWE CHE TUVALU U.S. MINOR OUTLYING ISL. UGANDA UKRAINIAN SSR UNITED ARAB EMIRATES UNITED KINGDOM UNITED STATES URAGUAY UZBEKISTAN TUV UMI UGA UKR ARE GBR USA URY UZB 141 DRAFT VeriSign, Inc.

154 Payflow Pro Developer s Guide -- Table H-1 MasterCard Country Codes VANUATU VATICAN CITY STATE VENEZUELA VIETNAM VIRGIN ISLANDS BRITISH VIRGIN ISLANDS US WALLIS AND FUTUNA IS WESTERN SAHARA YEMEN YUGOSLAVIA ZAIRE ZAMBIA ZIMBABWE VUT VAT VEN VNM VGB VIR WLF ESH YEM YUG ZAR ZMB RHO Visa Country Codes Table H-2 Visa Country Codes Table H-2 Visa Country Codes ALBANIA AL ARGENTINA AR ALGERIA DZ ARMENIA AM AMERICAN SAMOA AS ARUBA AW ANDORRA AD AUSTRALIA AU ANGOLA AO AUSTRIA AT ANGUILLA AI AZERBAIJAN AZ ANTARCTICA AQ BAHAMAS BS ANTIGUA AG BAHRAIN BH APHGANISTAN AF BANGLADESH BD 142 DRAFT VeriSign, Inc.

155 Payflow Pro Developer s Guide -- Table H-2 Visa Country Codes Table H-2 Visa Country Codes BARBADOS BB CHILE CL BELARUS BY CHINA CN BELGIUM BE CHRISTMAS ISLAND CX BELIZE BENIN BERMUDA BHUTAN BOLIVIA BOSNIA AND HERZIGOVINA BZ BJ BM BT BO BA CMEROON, UNITED REP. COLUMBIA COMOROS CONGO COOK ISLANDS COSTA RICA CM CO KM CG CK CR BOTSWANA BW COTED'IVOIRE CI BOUVET ISLAND BV CROATIA HR BRAZIL BR CYPRUS CY BRITISH INDIAN OCEAN TERRITORY BRUNEI BULGARIA BURKINA FASO BURUNDI IO BN BG BF BI CZECH REPUBLIC DENMARK DJIBOUTI DOMINICA DOMINICAN REPUBLIC CZ DK DJ DM DO CAMBODIA KH EAST TIMOR TP CANADA CA ECUADOR EC CAPE VERDE CV EGYPT EG CAYMAN ISLANDS KY EL SALVADOR SV CENTRAL AFRICAN REPUBLIC CF EQUATORIAL GUINEA GQ CHACOS (KEELING) ISLAND CHAD CC TD ERITREA ESTONIA ETHIOPIA ER EE ET 143 DRAFT VeriSign, Inc.

156 Payflow Pro Developer s Guide -- Table H-2 Visa Country Codes Table H-2 Visa Country Codes FAEROE ISLANDS FO HAITI HT FALKLAND ISLANDS FIJI FK FJ HEARD & MCDONALDS ISLAND HM FINLAND FI HONDURAS HN FRANCE FR HONG KONG HK FRENCH GUIANA GF HUNGARY HU FRENCH METROPOLITAN FRENCH POLYNESIA FX PF ICELAND INDIA INDONESIA IS IN ID FRENCH SOUTHERN TERRITORY TF IRAN IRAQ IR IQ GABON GA IRELAND IE GAMBIA GM ISRAEL IL GEORGIA GE ITALY IT GERMANY DE JAMAICA JM GHANA GH JAPAN JP GIBRALTER GI JORDAN JO GRECE GR KAZAKHSTAN KZ GREENLAND GL KENYA KE GRENADA GD KIRIBATI KI GUADALUPE GUAM GUATEMALA GUINEA GUINEA-BISSAU GP GU GT GN GW KOREA, REPUBLIC OF KUWAIT KYRGYZSTAN LAO PEOPLES DEMOCRATIC KR KW KG LA GUYANA GY LATVIA LV 144 DRAFT VeriSign, Inc.

157 Payflow Pro Developer s Guide -- Table H-2 Visa Country Codes Table H-2 Visa Country Codes LEBANON LB MONTSERRAT MS LESOTHO LS MOROCCO MA LIBERIA LR MOZAMBIQUE MZ LIBYAN ARAB JAMAHIRIYA LIECHTNSTIEN LITHUANIA LUXEMBOURG MACAU MACEDONIA LY LI LT LU MO MK MYANMAR NAMIBIA NAURU NEPAL NETHERLANDS NETHERLANDS ANTILLES MM NA NR NP NL AN MADAGASCAR MG NEW CALDONIA NC MALAWI MW NEW ZEALAND NZ MALAYSIA MY NICARAGUA NI MALDIVES MV NIGER NE MALI ML NIGERIA NG MALTA MT NIUE NU MANACO MC NORFOLK ISLAND NF MARSHALL ISLANDS MH NORTHERN MARIANA ISLAND MP MATINIQUE MQ NORWAY NO MAURITANIA MR OMAN OM MAURITIUS MU PAKISTAN PK MAYOTTE YT PALAU PW MEXICO MX PANAMA PA MICRONESIA FM PAPAU NEW GUINEA PG MOLDOVA MD PARAGUAY PY MONGOLIA MN PERU PE 145 DRAFT VeriSign, Inc.

158 Payflow Pro Developer s Guide -- Table H-2 Visa Country Codes Table H-2 Visa Country Codes PHILIPPINES PH SUDAN SD PITCAIRN ISLAND PN SURINAM SR POLAND PORTUGUL PUERTO RICO QATAR REUNION ROMANIA PL PT PR QA RE RO SVALBARD & JAN MAYEN IS. SWAZILAND SWEDEN SWITZERLAND SYRIAN ARAB REPUBLIC SJ SZ SE CH SY RUSSIAN FERERATION RWANDA SAMOA SAN MARINO SAN TOME AND PRICIPEL SAUDI ARABIA SENEGAL SEYCHELLES SIERRA LEONE SINGAPORE ST. HELENA ST. KITTS-NEVIS-ANGUI LLA ST. LUCIA ST. PIERRE AND MIQUELON ST. VINCENT AND THE GRENADINES RU RW WS SM ST SA SN SC SL SG SH KN LC PM VC TAIWAN, PROVIDENCE OF CHINA TAJIKISTAN TANZANIA, UNITED REPUBLIC THAILAND TOGO TOKELAU TONGA TRINIDAD AND TOBAGO TUNISIA TURKEY TURKMENISTAN TURKS & CAICOS ISLANDS TUVALU U.S. MINOR OUTLYING ISL. UGANDA TW TJ TZ TH TG TK TO TT TN TR TM TC TV UM UG 146 DRAFT VeriSign, Inc.

159 Payflow Pro Developer s Guide -- Table H-2 Visa Country Codes UKRAINIAN SSR UNITED ARAB EMIRATES UNITED KINGDOM UNITED STATES URAGUAY UZBEKISTAN VANUATU VATICAN CITY STATE VENEZUELA VIETNAM VIRGIN ISLANDS BRITISH VIRGIN ISLANDS US WALLIS AND FUTUNA IS WESTERN SAHARA YEMEN YUGOSLAVIA ZAIRE ZAMBIA ZIMBABWE UA AE GB US UY UZ VU VA VE VN VG VI WF EH YE YU ZR ZM ZW Units of Measure Table H-3 Units of Measure Acre (4840 yd2) ACR Table H-3 Units of Measure Alcoholic strength by volume ASV Alcoholic strength by mass ASM Ampere* AMP 147 DRAFT VeriSign, Inc.

160 Payflow Pro Developer s Guide -- Table H-3 Units of Measure Table H-3 Units of Measure Ampere=hour (3,6 kc)* AMH Cubic foot FTQ Are (100 m2) ARE Cubic inch INQ Bar* BAR Cubic metre per hour* MQH Barrel (petroleum) (158,987 dm3) Becquerel* Billion EUR Billion US Board foot Brake horse power (245,7 watts) BLL BQL BIL MLD BFT BHP Cubic metre per second* Cubic metre* Cubic millimetre* Cubic yard Curie Day* Decade (ten years) MQS MTQ MMQ YDQ CUR DAY DEC British thermal unit (1,055 kilojoules) Bushel (35,2391 dm3) Bushel (36,36874 dm3) Candela* Carrying capacity in metric tonnes Cental GB (45, kg) Center, metric (100 kg) (syn.: Hectokilogram) BTU BUA BUI CDL CCT CNT DTN Decare Decilitre* Decimetre* Decitonne* Degree Celsius Degree Fahrenheit Degree Kelvin: Kelvin Displacement tonnage Dozen DAA DLT DMT DTN CEL FAH DPT DZN Centigram* CGM Dozen packs DZP Centilitre* CLT Dozen pairs DZR Centimetre* CMT Dozen pieces DCP Cord (3,63 m3) WCD Dozen rolls DRL Coulomb per kilogram* CKG Drachm GB (3, g) DRM Coulomb* COU Dram GB (1, g) DRI Cubic centimetre* CMQ Dram US (3, g) DRA Cubic decimetre* DMQ Dry Barrel (115,627 dm3) BLD 148 DRAFT VeriSign, Inc.

161 Payflow Pro Developer s Guide -- Table H-3 Units of Measure Table H-3 Units of Measure Dry gallon (4, dm3) GLD Hectometre* HMT Dry pint (0,55061 dm3) PTD Hertz* HTZ Dry quart (1, dm3) QTD Hour* HUR Farad* FAR Hundred CEN Fluid ounce (28,413 cm3) OZI Hundred boxes BHX Fluid ounce (29,5735 cm3) Foot (0,3048 m) Gallon (4, dm3) Gigabecquerel* Gigawatt-hour (1 million kw/h)* Gill (0, dm3) Gill (11,8294 cm3) Grain GB, US (64, mg) OZA FOT GLI GBQ GWH GII GIA GRN Hundred international units Hundred leaves Hundred packs Hundredweight US (45,3592 kg) Inch (25,4 mm) Joule* Kelvin* Kilobar* HIU CLF CNP CWA INH JOU KEL KBA Gram of fissile isotopes GFI Kilogram of caustic potash KPH Gram* GRM Kilogram of caustic soda KSH Great gross (12 gross) Gross Gross (register) ton Half year (six months) GGR GRO GRT SAN Kilogram of named substance Kilogram of nitrogen Kilogram of phosphonic anhydride KNS KNI KPP Hectare Hectobar* Hectogram* Hectokilogram* Hectolitre of pure alcohol HAR HBA HGM DTH HPA Kilogram of phosphorus pentoxide Kilogram of potassium hydroxide Kilogram of potassium oxide KPP KPH KPO Hectolitre* HLT Kilogram of sodium hydroxide KSH 149 DRAFT VeriSign, Inc.

162 Payflow Pro Developer s Guide -- Table H-3 Units of Measure Table H-3 Units of Measure Kilogram of substance 90 percent dry KSD (long) hundredweight GB (50, kg) CWI Kilogram per cubic meter* KMQ Lumen* LUM Kilogram per second* KGS Lux LUX Kilogram* KGM Megahertz* MHZ Kilohertz* KHZ Megalitre* MAL Kilojoule* KJO Megametre* MAM Kilometre per hour* KMH Megapascal* MPA Kilometre* Kilopascal* Kilorgram of uranium Kilotonne* KMT KPA KUR KTN Megavolt-ampere (1000 KVA)* Megawatt* Megawatt-hour (100 kw/h)* MVA MAW MWH Kilovar Kilovolt* Kilovolt-ampere* Kilowatt* Kilowatt-hour* Knot (1 nautical mile per hour) Leaf Liquid gallon (3,78541 dm3) KVR KVT KVA KWT KWH KNT LEF GLL Metre per second squared* Metre per second* Metre* Metric carat (200 mg=2,10-4 kg) Metric ton (1000 kg) Milliard Millibar* Millicurie MSK MTS MTR CTM TNE MLD MBR MCU Liquid pint (0, dm3) PTL Milligram* MGM Liquid quart (0, dm3) Litre (1 dm3)* Litre of pure alcohol Long ton GB, US (1, t) QTL LTR LPA LTN Millilitre* Millimetre* Million Million cubic metres* Million international units MLT MMT MIO HMQ MIU 150 DRAFT VeriSign, Inc.

163 Payflow Pro Developer s Guide -- Table H-3 Units of Measure Table H-3 Units of Measure Minute* MIN Quart (1, dm3) QTI Month MON Quarter (of a year) QAN Nautical mile (1852 m) Net (register) ton Newton* Number Number of articles Number of bobbons Number of cells* Number of international units NMI NTT NEW NMB NAR NBB NCL NIU Quarter, GB (12, kg) Quintal, metric (100 kg) Revolution per minute* Revolution per second* Score scruple, GB (1, g) Second* Set QTR DTN RPM RPS SCO SCR SEC SET Number of packs NMP Shipping ton SHT Number of pairs Number of parcels Number of parts NMR NPL NPT Short standard (7200 matches) Short ton GB, US (0, t) SST STN Number of rolls NRL Siemens* SIE Ohm* OHM Square centimetre* CMK Ounce GB, US (28, g) Ounce GB, US (31, g) (syn: Troy ounce) ONZ APZ Square decimetre* Square foot Square inch DMK FTK INK Pascal* PAL Square kilometre* KMK Pennyweight GB, US ( g) Piece Pint (0, dm3) Pound GB, US (0, kg) DWT PCE PTI LBR Square metre* Square mile Square millimetre* Square yard Standard MTK MIK MMK YDK WSD Proof gallon PGL 151 DRAFT VeriSign, Inc.

164 Payflow Pro Developer s Guide -- Table H-3 Units of Measure Table H-3 Units of Measure standard atmosphere ( Pa) (statue) mile (1609,344 m) ATM SMI Yard (0,9144 m) Year YRD ANN Stone GB (6, kg) STI Technical atmosphere (98066,5 Pa) ATT Ten days DAD Ten pairs TPR Thousand MIL Thousand ampere-hour* TAH Thousand board feet (2,36 m3) MBF Thousand cubic metres per day* TQD Thousand standard brick equivalent MBE Ton of steam per hour TSH Tonne (1000 kg)* TNE Tonne of substance 90 percent dry TSD Trillion EUR TRL Trillion US BIL Troy ounce APZ Troy pound, US (373,242 g) LBT Volt* VLT Watt* WTT Watt-hour* WHR Weber WEB Week WEE 152 DRAFT VeriSign, Inc.

165 Payflow Pro Developer s Guide -- FDMS South Currency Codes and Decimal Positions Table H-4 FDMS South Currency Codes and Decimal Positions Currency Name Currency Code Decimal Positions Argentine Peso 32 2 Australian Dollar 36 2 Austrian Schilling 40 2 Belgian Franc 56 0 Canadian Dollar Chilean Peso Czech Koruna Danish Krone Dominican Peso Markka French Franc Deutsche Mark Drachma Hong Kong Dollar Indian Rupee Irish Punt Shekel Italian Lira Yen Won Luxembourg Franc Mexican Duevo Peso Netherlands Guilder New Zealand Dollar DRAFT VeriSign, Inc.

166 Payflow Pro Developer s Guide -- Table H-4 FDMS South Currency Codes and Decimal Positions (Continued) Norwegian Frone Philippine Peso Portuguese Escudo Rand Spanish Peseta Swedish Krona Swiss Franc Thailand Baht Pound Sterling Russian Ruble U.S Dollar Bolivar New Taiwan Dollar Euro Polish New Zloty Brazilian Real DRAFT VeriSign, Inc.

167 xi Apend APPENDIX I IEnsuring Safe Storage and Use of Passwords You should always secure passwords and strive to eliminate unwanted access. Store passwords in encrypted form behind a properly configured firewall. This includes passwords in scripts, code, pages, logs, and databases. This appendix describes the example Payflow Pro Encrypted Password program. Overview of the Risks Here is a partial list of the risks of exposing your Payflow Pro password: + A hacker could issue fraudulent transactions using stolen credit cards. + A hacker could buy a product using a sale transaction, receive the downloaded product, and then void the transaction before settlement. + If the ability to issue credits is not disabled for your account, a hacker could fraudulently credit funds out of your account into: A stolen credit card s account (enabling further purchases) An offshore account accessible by the hacker. Such funds are not recoverable within the U.S. legal system. Tip VeriSign strongly recommends that you do not store credit card numbers at all. If you must store credit card numbers, then store them in encrypted form behind a properly configured firewall. VeriSign, Inc /Rev

168 VeriSign Payment Services Payflow Pro Developer s Guide Fraud Prevention Resources For more information about preventing fraud, see: For information about VeriSign Manager security features that reduce unauthorized access to your account, see: Overview of the Example Password Encryption Program CAUTION Do not use VeriSign's example scripts in your production environment. You must write a program that encrypts and decrypts your PayFlow Pro account password. In actual practice, you must ensure that the file containing the key and the file containing the encrypted password are kept where they cannot be accessed or read except by the application that submits transactions. The Payflow Pro Encrypted Password program provides an example of the process of dynamically generating a symmetric key, then using the key to encrypt the password. The script then stores the encrypted password file in a newly created lib subdirectory in a dynamically generated jar file that will be accessed as a java resource whenever the password is required. In this example, the symmetric key and the encrypted password reside on the same host. Included Files Code listings for the following files appear in Code Listings on page 158. Figure I-1 Included Files File PFProEncrypt.jav a encrypt.pl PFProSecure.java securetest.pl Description Sample java file Perl test script to encrypt and store the password. Sample java file Perl test script to decrypt the password and submit transactions with the decrypted password. 156 VeriSign, Inc /Rev. 3

169 Appendix I Ensuring Safe Storage and Use of Passwords Requirements Payflow Pro Java SDK Client version You can download the code from the Downloads page in the VeriSign Manager: Encrypting the Password Step 1 Configure the Script The example Perl scripts provided by VeriSign set the CLASSPATH, and call javac for the java file each time the script is run. The script finally runs the java command on the compiled java class passing any needed parameters. To prepare the encrypt.pl script, you must specify actual merchant values for the account variables. Modify the encrypt.pl Perl script as follows: Replace the default text values with actual merchant values for the following account variables: $user, $vendor, $partner, and $password. Step 2 Encrypt the Password Run the encrypt.pl Perl script once to initialize the key file and encrypt the password file. The script then stores the encrypted password file in a newly created lib subdirectory in a jar file that will be accessed as a java resource. >Perl encrypt.pl Step 3 Delete the files used to encrypt the password After encrypting the password, you must delete the files used to generate the password because both the password and method of encrypting it are contained within the files. Follow these steps: 1 Rename the../lib/$encjar file and move it to a unique location so that its location and filename are difficult to discover. Delete $encjar from../lib. Specify the new location and name in the CLASSPATH reference in the securetest.pl script. Alternatively, specify the path information from the command line when executing the PFProSecure java command. VeriSign, Inc /Rev

170 VeriSign Payment Services Payflow Pro Developer s Guide 2 To enable you to change the password in the future, move the following files to a safe location and then delete the files from their current location: $keyfile (encrypt.pl provides the location) $encfile (encrypt.pl provides the location) PFProEncrypt.java PFProEncrypt.class readme.txt encrypt.pl Submitting Transactions Using the Encrypted Password Run the securetest.pl Perl test script for all test transactions. Code Listings >Perl securetest.pl encrypt.pl Code Listing #!/usr/bin/perl ########################## use File::Copy; use Config; $: = $Config{path_sep}; # Set environment $LIBS = "$:.$:..$:../lib"; $ENV{PATH}.=$LIBS; $ENV{LD_LIBRARY_PATH}.=$LIBS; $ENV{SHLIB_PATH}.=$LIBS; $ENV{LIBPATH}.=$LIBS; $ENV{CLASSPATH}.= "$:../lib/verisign.jar$:../lib/jsse/jnet.jar$:../lib/jsse/jcert.jar$:../lib/jsse/jsse.jar$:."; $ENV{PFPRO_CERT_PATH} = "../../dist/java/certs"; # Merchant Account values # => Change these to your account values $user = "user"; $vendor = "vendor"; $partner = "partner"; 158 VeriSign, Inc /Rev. 3

171 Appendix I Ensuring Safe Storage and Use of Passwords $password = "password"; # => Change the above to your account values $JDKBIN="C:/j2sdk1.4.0/bin"; # Compile the code print `$JDKBIN/javac PFProEncrypt.java`; $encjar = "eqabz.jar"; $keyfile = "key"; $encfile = "encrypted"; # Run the test print `$JDKBIN/java PFProEncrypt -user $user -vendor $vendor -partner $partner -password $password`; print `$JDKBIN/jar cm0f $encjar $keyfile $encfile`; mkdir("../lib",0744); copy($encjar,"../lib"); print "\n"; PFProEncrypt.java Code Listing // Verisign, Inc. // // See contact.txt for additional contact information // Verisign Payflow Pro Encrypted Password Sample import java.security.generalsecurityexception; import java.security.keypair; import java.security.keypairgenerator; import java.security.nosuchalgorithmexception; import java.security.privatekey; import java.security.publickey; import java.security.cert.x509certificate; import java.security.interfaces.rsakey; import java.io.*; import java.security.*; import javax.crypto.*; import javax.crypto.spec.*; class PFProEncrypt { public static void encode(string user, String vendor, String partner, String password) throws Exception { VeriSign, Inc /Rev

172 VeriSign Payment Services Payflow Pro Developer s Guide System.out.println("Encrypting...\n"); // // Generate a symmetric key using the DES algorithm. // System.out.println(" Generating key...\n"); KeyGenerator kg = KeyGenerator.getInstance("DES"); kg.init(new SecureRandom()); SecretKey key = kg.generatekey(); SecretKeyFactory kf = SecretKeyFactory.getInstance("DES"); Class deskeyspec = Class.forName("javax.crypto.spec.DESKeySpec"); DESKeySpec keyspec = (DESKeySpec) kf.getkeyspec(key, deskeyspec); ObjectOutputStream keyfile = new ObjectOutputStream(new FileOutputStream("key")); keyfile.writeobject(keyspec.getkey()); Cipher c = Cipher.getInstance("DES/CBC/PKCS5Padding"); c.init(cipher.encrypt_mode, key); CipherOutputStream pwdfile = new CipherOutputStream( new FileOutputStream("encrypted"), c); PrintWriter pw = new PrintWriter( new OutputStreamWriter(pwdfile) ); System.out.println(" writing encrypted values:\n"); System.out.println(" user: " + user + "\n"); pw.println(user); System.out.println(" vendor: " + vendor + "\n"); pw.println(vendor); System.out.println(" partner: " + partner + "\n"); pw.println(partner); System.out.println(" password: " + password + "\n"); pw.println(password); pw.close(); keyfile.writeobject(c.getiv()); keyfile.close(); } System.out.println("Done.\n"); static private void usage() { java.io.printstream p = System.out; p.println("syntactic usage:\n"); p.println("java " + PFProEncrypt.class.getName() + "-user <user name>" + "-password <user password>" + "-vendor <vendor name>" + "-partner <partner name (case sensitive)>\n"); } public static void main(string argv[]) { 160 VeriSign, Inc /Rev. 3

173 Appendix I Ensuring Safe Storage and Use of Passwords } try { if (argv.length < 2 argv[0].equals("-h")) { usage(); return; } String user = findvalue("-user", argv); String password = findvalue("-password", argv); String vendor = findvalue("-vendor", argv); String partner = findvalue("-partner", argv); System.out.println(password); encode(user, vendor, partner, password); //password = null; //System.out.println(password); //password = decode(); //System.out.println(password); } catch (Exception e) { System.out.println(e); } static private String findvalue(string tofind, String argv[]){ return findvalue(false, tofind, argv); } static private boolean find(string tofind, String argv[]){ return find(false, tofind, argv); } static private String findvalue(boolean required, String tofind, String argv[]){ for (int i = 0; i < argv.length; ++i){ if (argv[i].equals(tofind)){ return nextargv(argv, i); } } if (required) { throw new IllegalArgumentException("'" + tofind + "' argument missing in input"); } else { return null; } } static private boolean find(boolean required, VeriSign, Inc /Rev

174 VeriSign Payment Services Payflow Pro Developer s Guide } String tofind, String argv[]){ for (int i = 0; i < argv.length; ++i){ if (argv[i].equals(tofind)){ String s = nextargv(argv, i); return true; } } if (required) { throw new IllegalArgumentException("'" + tofind + "' argument missing in input"); } else { return false; } /** * Returns the next entry in argv, unless it starts with * a '-' (to catch errors such as 'java xyz -a -b' where * '-a' needs a value 'java xyz -a value -b' */ private static String nextargv(string[] argv, int i){ if ((argv[i+1]!= null) && (!argv[i+1].startswith("-"))){ return argv[i+1]; } else { return null; } } } securetest.pl Code Listing #!/usr/bin/perl ########################## use Config; $: = $Config{path_sep}; # Set environment $LIBS = "$:.$:..$:../lib"; $ENV{PATH}.=$LIBS; $ENV{LD_LIBRARY_PATH}.=$LIBS; $ENV{SHLIB_PATH}.=$LIBS; $ENV{LIBPATH}.=$LIBS; # Directory containing the JSSE jar files # => Change this to your JSSE jar file directory 162 VeriSign, Inc /Rev. 3

175 Appendix I Ensuring Safe Storage and Use of Passwords $JSSEDIR = "../lib/jsse"; # => Change above to your JSSE jar file directory $JSSECLASSPATH = "$:$JSSEDIR/jsse.jar$:$JSSEDIR/jcert.jar$:$JSSEDIR/jnet.jar"; $ENV{CLASSPATH}.= "$:../lib/eqabz.jar$:verisign.jar$:.$:$jsseclasspath"; $ENV{PFPRO_CERT_PATH} = "../certs"; $JDKBIN="C:/j2sdk1.4.0/bin"; # Compile the code print `$JDKBIN/javac PFProSecure.java`; # Run the test print `$JDKBIN/java PFProSecure test-payflow.verisign.com 443 "TRXTYPE=S&TENDER=C&ACCT= &EXPDATE=1209&AMT=14.42&C OMMENT1[3]=123&COMMENT2=Good Customer&INVNUM= &STREET=5199 JOHNSON&ZIP=94588" 30`; print "\n"; PFProSecure.java Code Listing // Verisign, Inc. // // See contact.txt for additional contact information // Verisign Payflow Pro Encrypted Password Sample import com.verisign.payment.pfproapi; import java.security.generalsecurityexception; import java.security.keypair; import java.security.keypairgenerator; import java.security.nosuchalgorithmexception; import java.security.privatekey; import java.security.publickey; import java.security.cert.x509certificate; import java.security.interfaces.rsakey; import java.io.*; import java.security.*; import javax.crypto.*; import javax.crypto.spec.*; class PFProSecure { public static class UserAuth { public String user= "user"; VeriSign, Inc /Rev

176 VeriSign Payment Services Payflow Pro Developer s Guide public String vendor= "vendor"; public String partner= "partner"; public String password= "password"; } public String tostring() { return ("&USER=" + user + "&PWD=" + password + "&VENDOR=" + vendor + "&PARTNER=" + partner); } public static UserAuth decode() throws Exception { System.out.println("Decrypting...\n"); System.out.println(" Retrieving key...\n"); ObjectInputStream keyfile = new ObjectInputStream( PFProSecure.class.getResourceAsStream("key") ); DESKeySpec ks = new DESKeySpec((byte[]) keyfile.readobject()); SecretKeyFactory kf = SecretKeyFactory.getInstance("DES"); SecretKey key = kf.generatesecret(ks); Cipher c = Cipher.getInstance("DES/CBC/PKCS5Padding"); c.init(cipher.decrypt_mode, key, new IvParameterSpec((byte[]) keyfile.readobject())); CipherInputStream pwdfile = new CipherInputStream(PFProSecure.class.getResourceAsStream("encrypted"), c); BufferedReader br = new BufferedReader( new InputStreamReader(pwdfile) ); System.out.println(" reading encrypted values:\n"); UserAuth userauth = new UserAuth(); userauth.user = br.readline(); System.out.println(" user: " + userauth.user + "\n"); userauth.vendor = br.readline(); System.out.println(" vendor: " + userauth.vendor + "\n"); userauth.partner = br.readline(); System.out.println(" partner: " + userauth.partner + "\n"); userauth.password = br.readline(); System.out.println(" password: " + userauth.password + "\n"); System.out.println("Done.\n"); return userauth; } // Set defaults static String HostAddress = "test-payflow.verisign.com"; static Integer HostPort = Integer.decode("443"); 164 VeriSign, Inc /Rev. 3

177 Appendix I Ensuring Safe Storage and Use of Passwords static String ParmList = ""; static Integer Timeout = Integer.decode("30"); static String ProxyAddress = ""; static Integer ProxyPort = Integer.decode("0"); static String ProxyLogon = ""; static String ProxyPassword = ""; static UserAuth userauth = null; // Help system static void help() { System.out.println( "Usage Error: \n" ); System.out.println("pfpro <hostaddress> <hostport> <parmlist> <timeout> <proxyaddress> <proxyport> <proxylogon> <proxypassword>"); System.out.println("<hostAddress> host name 'test-payflow.verisign.com'"); System.out.println("<hostPort> host port number '443'"); System.out.println("<parmList> parameter list 'ccnum= &ccexpdate=1299&amount=1.23'"); System.out.println("<timeOut> timeout(sec) - optional '30'"); System.out.println("<proxyAddress> proxy name - optional 'proxy'"); System.out.println("<proxyPort> proxy port - optional '8080'"); System.out.println("<proxyLogon> proxy logon name - optional 'admin'"); System.out.println("<proxyPassword> proxy password - optional 'password'"); } public static void main(string[] args) { try { userauth = decode(); } catch (Exception e) { System.out.println(e); } PFProAPI pn = new PFProAPI(); // Check args, at least the first 3 must be there if (args.length < 3) { System.out.println( "\npfpro " + pn.version() ); try { if ( args[0].equalsignorecase(new String("-version")) ) { System.out.println(); VeriSign, Inc /Rev

178 VeriSign Payment Services Payflow Pro Developer s Guide return; } } catch (Exception e) { } } help(); return; // Place the arguments in the correct variables // Once we get an OutOfBounds exception, parsing will stop // and the rest will retain their default values. try { HostAddress = args[0]; HostPort = Integer.decode(args[1]); ParmList = args[2]; Timeout = Integer.decode(args[3]); ProxyAddress = args[4]; ProxyPort = Integer.decode(args[5]); ProxyLogon = args[6]; ProxyPassword = args[7]; } catch (Exception e) { } // Set the certificate path pn.setcertpath("../certs"); // Call the client. pn.createcontext(hostaddress, HostPort.intValue(), Timeout.intValue(), ProxyAddress, ProxyPort.intValue(), ProxyLogon, ProxyPassword); String rc = pn.submittransaction( ParmList + userauth ); System.out.println(rc); } } pn.destroycontext(); 166 VeriSign, Inc /Rev. 3

179 xi Apend APPENDIX J JFrequently Asked Questions Where do I find online information about Payflow Pro? See: How do I download the VeriSign SDK? Log in to VeriSign Manager and click Downloads. All VeriSign SDKs are listed by server platform and operating system. All SDKs are contained in downloadable WinZip files. You can download WinZip at Do I need the VeriSign SDK if I already have a shopping cart? Refer to your shopping cart documentation to verify its compatibility with VeriSign. Your shopping cart documentation should specify if it is pre-integrated or requires a VeriSign SDK plug-in. Shopping cart SDKs are available on VeriSign s Manager s Downloads page. How do I know my transactions are connecting to VeriSign? We send your server a 12-character PNREF (for example, VXES ) for every transaction submitted to our servers. The PNREF appears in VeriSign Manager Reports as the Transaction ID. For Test transactions, the first and fourth characters in the PNREF value are alpha characters (letters), and the second and third characters are numeric (Example: V53A ). For Live transactions, all of the first four characters are alpha characters, for example: VPNE How do I process test transactions? Once you have registered with VeriSign and have completed the integration/configuration of your storefront use the following information to begin testing transactions: HostAddress: test-payflow.verisign.com HostPort: 443 PARTNER: Your partner ID or VeriSign VeriSign, Inc /Rev

180 VeriSign Payment Services Payflow Pro Developer s Guide VENDOR: Your case-sensitive login USER: Your case-sensitive login PWD: Your case-sensitive password How do I process live transactions? Once you have successfully processed test transactions, use the following information to reconfigure your storefront: HostAddress: payflow.verisign.com HostPort: 443 PARTNER: Your partner ID or VeriSign VENDOR: Your case-sensitive login USER: Your case-sensitive login PWD: Your case-sensitive password Is the SDK thread-safe? Yes. All of our SDKs are thread-safe. Can you provide guidelines about using the various Payflow SDKs to process transactions in a multi-threaded environment? First, pfproinit() must be called at the start of the main thread, and pfprocleanup() must be called at its finish. You can create multiple threads, each with multiple contexts, and send any number of transactions using each context. However, all threads must be created and completed between the calls to pfproinit() and pfprocleanup(). While it is possible to submit multiple transactions using a single context, we strongly recommend that you create a new context for each transaction. Example pseudo code: 1 CreateObject - to create the COM object 2 CreateContext - to setup the context and communication parameters 3 (Build a string containing all transaction parameters) 4 SubmitTransaction - Process the transaction 5 (Parse the string returned for result information) 6 DestroyContext - Destroy the context. 168 VeriSign, Inc /Rev. 3

181 Index Index A ACCT parameter 19 Address 38 Address Verification Service 38 American Express 6, 65 AMT parameter 19 APIs documentation 11 downloading 11 AUTHCODE 46 AUTHCODE parameter 19 AVS, see Verification Service AVSADDR 46 AVSZIP 46 C card security code card-present transaction 105 CHKNUM parameter 79 CITY 103 close batch see settlement operation COMMCARD 99 COMMENT1 parameter 19 COMMENT2 parameter 19 Common Gateway Interface 3 communications errors 53 COUNTRYCODE 101, 103 credit card types 4 credit card transaction required parameters 26 credit transaction type 27 CSC, see card security code CUSTCODE 103 CUSTREF parameter 20 CVV2 parameter 20 D DISCOUNT 101, 103 DL parameter 79 DOB field 79 documentation API 11 downloading APIs 11 DUTYAMT 99, 101, 103 E electronic check transaction required parameters 78 ENDTIME parameter 20 EXPDATE parameter 20 F FDMS Nashville 6, 67 FDMS North 101 FDMS South 7, 69, 99, 103 FIRSTNAME 103 FIRSTNAME parameter 20 FREIGHTAMT 100, 101, 104 DRAFT VeriSign, Inc /Rev

182 VeriSign Payment Services Payflow Pro Developer s Guide G Global Payments Central 7 Global Payments East 7 H HostAddress 17 HOSTPORT 17 I inquiry transaction type 31 INVNUM 67, 71, 73, 104 L LASTNAME 104 length tags 18, 77 live transactions 168 logging transaction information 43, 82 M MAPP 7 MICR field 79 N NAME parameter 20 NDCE 7 Nova 7, 70 O ORDERDATE 104 ORIGID parameter 21 P parameters required for credit card 26 required for electronic check 78 PARMLIST 17 Partner Manager overview 9 PARTNER parameter 21 Payflow Pro 1 library formats 1, 12 software formats 1, 12 Payflow Pro client payment types 5 Paymentech 7, 71 pfpro, see Payflow Pro client PHONENUM field 79 PNREF 45, 83 format of value 47 PNREF value 46 PONUM 100, 101, 105 processing 4 processors Wells Fargo Bank 8 PROXYADDRESS 18, 76 PROXYLOGON 18, 77 PROXYPASSWORD 18, 77 PROXYPORT 18, 76 purchase card line item parameters 105 PWD parameter 21 R required parameters credit card 26 electronic check 78 RESPMSG 46, 83 RESPMSG value 48 responses credit card transaction 45 RESULT 45, 83 RESULT value 47 RESULT values communication errors 53 DRAFT 170 VeriSign, Inc /Rev. 3

183 Index S sale transaction type 27 SDK 1 Secure Sockets Layer 2 security AVS 38 CSC settlement operation 2 SHIPFROMZIP 101, 105 SHIPTOZIP 100, 102, 105 shopping carts 11, 167 Software Development Kit 1 SS field 80 SSL, see Secure Sockets Layer STARTTIME parameter 21 STATE 105 Street field 80 STREET parameter 21 SWIPE parameter 22 swipe transaction 105 syntax 17, 76 T TAXAMT 100, 102, 105 TAXEXEMPT 100, 105 TCP 1 TeleCheck 7, 75 TENDER parameter 22 test transactions 167 TIMEOUT 18, 76 transaction format 17 transaction response PNREF parameter 46 RESPMSG parameter 48 RESULT parameter 47 transactions commercial card 35 creating 26 credit 27 inquiry 31 sale 27 voice authorization 30 void 29 TRXTYPE parameter 22 U USER parameter 22 V VENDOR parameter 22 VERBOSITY parameter 23 Vital 8, 73 voice authorization transaction type 30 void transaction type 29 W Wells Fargo Bank 8 Z ZIP parameter 23 DRAFT VeriSign, Inc /Rev

184 VeriSign Payment Services Payflow Pro Developer s Guide DRAFT 172 VeriSign, Inc /Rev. 3