Payflow Gateway Developer Guide and Reference

This guide is intended for developers integrating with PayPal Payments Pro, PayPal Payments Advanced, Payflow Pro or Payflow Link. See the Intended Audience section for further information.

Contents

• Preface
• Introducing the Gateway Checkout Solutions
• Secure Token
• Configuring Hosted Checkout Pages
• Payflow SDK
• Sending a Simple Transaction to the Server
• Submitting Credit Card Transactions
• Testing Transactions
• Transaction Responses
• Processors Requiring Additional Transaction Parameters
• TeleCheck Electronic Check Processing
• Payflow Header Parameters
• Submitting Purchasing Card Level 2 and 3 Transactions
• VERBOSITY - Processor-Specific Transaction Results
• Country Codes
• Codes Used by FDMS South Only
• Units of Measurement Codes
• Additional Processor Information
• Payflow Link Migration
• Payflow Gateway MagTek Parameters
• Payflow Gateway Tokenization
• Payflow Gateway FAQs

Preface

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

Scope

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

The guide describes the requirements of an ever-growing list of processing platforms. Parameters in the guide are organized into various categories, which include a core set of request parameters supported by all processors, additional parameters unique to individual processors, and purchasing card parameters specialized to monitor credit card use in businesses. This guide also provides a section on response parameters and error codes.

Although this guide explains getting started with the SDK, setting up credit card processing, and testing your integration, this is not a tutorial on integration. Refer to the PayPal Developer website and the NVP/SOAP APIs - Payflow Gateway SDK for detailed working examples and use cases.

Related Documentation

For additional information on Payflow payments solutions:

• See PayPal Manager.

• For more documentation, examples, and very current information, see the PayPal developer site at Payflow Gateway / PayPal Payments Pro

Intended Audience

This guide provides Payflow Gateway payments solutions to readers who:

• are web or application developers
• have a background in payments services

Who Should Use This Document

This comprehensive developer guide includes integration information for multiple Payflow solutions.

Note: Legacy Payflow Link features are not included in this guide. For legacy Payflow Link features refer to the Payflow Link User's Guide.

Additionally, all Payflow features explained in this guide are not necessarily available to every Payflow customer. This section will help you determine whether you should use this document and which sections of the document are relevant to you.

To view the Payflow solutions available to you, log in to PayPal Manager. PayPal Manager displays your Payflow Services in the Service Summary box.

Payflow Link

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

a) Legacy Payflow Link merchants see the following in the Service Summary box in PayPal Manager:

Payflow Link

If you are a legacy Payflow Link merchant, do not use this guide; instead, use the Payflow Link User's Guide.

b) New Payflow Link merchants see the following in the Service Summary box in PayPal Manager:

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

If PayPal Payments Advanced is also listed, you are not a Payflow Link customer.

Use this guide if you are a new Payflow Link merchant who uses the Secure Token or API.

Use the Payflow Link User's Guide if you are a new Payflow Link merchant who uses the legacy Payflow Link input tag integration.

*Limited API Access means you can perform all API functions except for Sales and Authorization transactions. For Sales and Authorization type transactions you must use the Hosted Checkout Pages.

Payflow Pro

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

a) Legacy Payflow Pro merchants see the following in the Service Summary box in PayPal Manager:

Payflow Pro

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

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

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

PayPal Payments Advanced

Transactions submitted by PayPal Payments Advanced merchants are processed through the Gateway with PayPal acting as the merchant bank. PayPal Payments Advanced merchants can see the following in the Service Summary box in PayPal Manager:

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

Limited API Access means you can perform all API functions except for Sales and Authorization transactions. For Sales and Authorization type transactions you must use Hosted Checkout Pages.

PayPal Payments Pro

Transactions submitted by PayPal Payments Pro merchants are processed through the Gateway with PayPal acting as the merchant bank. PayPal Payments Pro merchants can use all of the Gateway features supported by PayPal. These merchants can see the following in the Service Summary box in PayPal Manager:

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

Revision History

Revision History for the Payflow Gateway Developer Guide and Reference:

10 Dec 2015

• Added a section on Echoing data back within Core Credit Card Parameters on the ECHODATA request field, its possible values and the fields that are echoed back for each possible value.
• Added the Payflow Gateway Tokenization chapter which only includes tokenization fields for the American Express processor at this time.
• Added a note to the TSYS Acquiring Solutions Level 3 Visa Line Item Detail Records section indicating that up to 999 line items can be submitted for TSYS level 3 Visa transactions, and a note to TSYS Acquiring Solutions Level 3 MasterCard Line Item Detail Records section indicating that up to 99 line items can be submitted for TSYS level 3 mastercard transactions.
• Updated the Testing Your PayPal Payments Advanced and PayPal Payments Pro Integration section to include more information on testing Payflow Express Checkout transactions using the PayPal Sandbox.

10 Nov 2015

• Corrected the names of the following parameters in the guide: VATAXAMT and VATAXPERCENT. Also, noted that the following fields should not contain more than two decimal places: ADDLAMTn, ALTTAXAMT, ALTERNATETAXAMT, LOCALTAXAMT, NATIONALTAXAMT and VATAXAMT.

15 Jun 2015

• Noted that MODE parameter is now deprecated.

23 Apr 2015

• Added a units of measurement codes reference table that can be used for unit of measurement parameters.

05 Apr 2015

• Clarified the format and uses of the PNREF response parameter.

30 Dec 2014

• Corrected the merchant soft descriptor fields supported by the PayPal processor. Use the MERCHDESCR and MERCHANTCITY fields to pass merchant name and contact information for sale and authorization transactions. This information is displayed on the account holder's statement. See the PayPal Credit Card Transaction Request Parameters section for details.

10 Dec 2014

• Updated the Paymentech Salem - New Hampshire - Level 3 Purchasing Card Parameters Level 2 and Level 3 parameters.
• Added info to the Submitting Purchasing Card Level 2 and 3 Transactions introduction clarifying that merchants are responsible for calculating and verifying Level 2 and 3 line item totals.
• Updated the TRANSSTATE field description in Credit Card Transaction Responses to include TRANSSTATE values returned when the Fraud Protection Service filters flag a transaction.

20 Nov 2014

• Updated Diner's club card number in Credit Card Numbers for Testing.

5 Nov 2014

• Added table of processors that support account verifications for each major credit card.

15 Oct 2014

• Clarified that the Payflow Gateway does not charge any fees for Account Verfications (zero amount authorizations); however, the merchant's processor, including PayPal as a merchant bank, may charge a fee for account verifications. For information on whether transaction fees are charged for the various Payflow credit card transaction types, see Credit Card Features.

19 Sep 2014

• Corrected the Paymentech Salem product code field name. Replaced the incorrect field name L_PRODCODEn with L_UPCn in Paymentech Salem Level 3 MasterCard Line Item Record 1 Parameters, Paymentech Salem Level 3 Visa Line Item Record 1 Parameters and Paymentech Salem Level 3 Visa Line Item Record 2 Parameters.

7 Aug 2014

• Merchant soft descriptor fields are now supported by the PayPal processor. Use the MERCHDESCR and MERCHANTCITY fields to pass merchant name and contact information for sale and authorization transactions. This information is displayed on the account holder's statement. See the PayPal Credit Card Transaction Request Parameters and Merchant Descriptor - M Record sections for details.

17 June 2014

• Added new Elavon Travel Parameters.
• Added a note to the Paymentech Salem - New Hampshire - Level 3 Purchasing Card Parameters section.

06 Mar 2014

• Expanded support for the HOSTCODE and EXTRSPMSG response fields for the WorldPay processor. (HOSTCODE and EXTRSPMSG return the processor's error code and message respectively.)

28 Feb 2014

• Added the Planet Payment processor, which supports Multi-Currency Pricing (MCP).
• Added a new transaction type, supported by Planet Payment only, for currency conversion rate lookups. See Submitting Rate Lookups.

18 Feb 2014

• Added new Litle Response Parameters and TSYS Response Parameters.
• Added the BILLTOSTREET2 request parameter to Core Credit Card Parameters.

07 Jan 2014

• Added Paymentech Tampa Level 2 Parameters.
• Updated processor name: Cielo Payments, formerly Merchant e-Solutions.

21 Nov 2013

• Updated the description of the CURRENCY field in PayPal Credit Card Transaction Request Parameters with information for PayPal Payments Advanced and PayPal Payments Pro merchants.

08 Nov 2013

• Added the TRANSSTATE response field description to Credit Card Transaction Responses.
• Added a note in When To Use a Sale Transaction for PayPal Payments Advanced or PayPal Payments Pro merchants using Fraud Protection Services (FPS).

31 Oct 2013

• Submitting Account Verifications is now supported by the PayPal processor.
• Added the CCTRANSID and CCTRANS_POSDATA response fields to Credit Card Transaction Responses; these two fields are currently supported for the TSYS processor only; they are useful for merchants who authorize transactions through the Gateway but settle through a third party.
• Clarified, in the Example Reference Transaction section, that the capture step of a reference transaction does not require the TENDER parameter.
• Clarified that the duration of the Secure Token is 30 minutes.
• Added a new section for Payflow Gateway FAQs.

20 Sep 2013

• Updated the character limits for billing and shipping address fields. These limits are different for the PayPal acquirer PayPal Credit Card Transaction Request Parameters compared with all other processors Core Credit Card Parameters.
• Provided clarification on which Country Codes to use for each of the following: the PayPal acquirer, TeleCheck, FDMS South, and for all other processors.
• Added a section about the The PayPal Manager Website.

19 Jul 2013

• Removed the ACCTTYPE parameter from this guide.

11 Jul 2013

• Maintenance release.
• Added a new section on Processor specific Response Parameters, which includes Litle Response Parameters and information on the litle-automatic-account-updater feature.
• Added information on Testing the Litle Automatic Account Updater Feature.

15 Jun 2013

• Added information on Submitting Refund Transactions for the PayPal processor.
• Added the PAYMENTADVICECODE field to Credit Card Transaction Responses.
• Added a note on problems with using legacy Payflow Link parameters with the Secure Token.
• Updated the support contact information for enabling PayPal processor line item support in the PayPal Credit Card Transaction Request Parameters table.
• Added a Level 3 Required Parameters table to TSYS Acquiring Solutions Level 3 Visa Parameters.
• Added information on Reference Authorizations and Sales specific to the PayPal processor in the Example Reference Transactionsection.
• Updated URL paths.

25 Apr 2013

• Updated the description of the Driver's Licencse DL field in Required TeleCheck Parameters.

22 Feb 2013

• Updated the description of the Driver's Licencse DL field in Required TeleCheck Parameters.

28 Jan 2013

• Added a new Appendix on Payflow Header Parameters.
• Added information about duplicate parameters in the Name Value Parameter Syntax Guidelines.
• In the Hosted Pages Chapter, added the Passing Other Data to Your Server Using Post or Silent Post section, and clarified that silent-posts are returned for both approved and declined transactions.
• Updated the Payflow Link legacy parameters and the equivalent Payflow parameters parameter table. Removed legacy Payflow Link parameters with identical Payflow equivalents.
• Updated the description of the parameters BILLTOSTATE and SHIPTTOSTATE in the Core Credit Card Parameters table.
• Added a note to the introduction of the Submitting Credit Card Transactions chapter.
• Revised the introduction to the Payflow SDK chapter.
• Updated some of the external links in the guide.
• Corrected the format of the ORDERDATE parameter in [TSYS Acquiring Solutions Level 3 Visa Parameters](#tsys acquiring solutions level 3 visa parameters).

28 Dec 2012

• Updated the description of the Driver's Licencse
• DL field in Required TeleCheck Parameters.

11 Dec 2012

• Added info on forcing the Cancel URL with layout template C to Configuring Hosted Pages Using PayPal Manager.
• Added Secure Token error codes to Secure Token Errors and to Result Values and RESPMSG Text.

04 Oct 2012

• Added a new section on Hosted Pages and Mobile Browsers and updated the Configuring Hosted Checkout Pages chapter.
• Added a new section: Supported Languages.
• Added a new section: Using the PARMLIST Parameter.
• Added information to the Host URL Addresses section.

29 Aug 2012

• Added the Payflow Gateway MagTek Parameters Appendix.

31 July 2012

• Added a list of Setup and Customize parameters in the section on Using a Secure Token to Pass Hosted Pages Customization Parameters. These parameters override PayPal Manager settings for Hosted Pages.
• Briefly explained the differences between Submitting Refund Transactions and Submitting Void Transactions.
• Updated the parameters in the Payflow Link legacy parameters and the equivalent Payflow parameters table.
• Added DATE_TO_SETTLE to Credit Card Transaction Responses parameters table.
• Added a note to the About Credit Card Processing section.

23 July 2012

• Added the Bill Me Later feature to the Gateway Product Details section.

16 July 2012

• Updated the value of the required column for the BILLTOCITY, BILLTOSTATE & BILLTOCOUNTRY parameters in PayPal Credit Card Transaction Request Parameters table.

June 2012

• Added the Who Should Use This Document section to the Preface.
• In the Integrating the Secure Token Without the Hosted Checkout Pages: Transparent Redirect section, corrected the value of SILENTTRAN to True.
• Added the Silent Posts section to the Hosted Checkout Pages chapter.
• Removed the legacy parameter CORPCOUNTRY from Country Codes.

May 2012

• Added new sections to the Testing Transactions chapter: Testing Address Verification ServiceTesting Card Security Code
• Added PayPal Acquirer chapter: Contains links to PayPal API Ref country and currency codes

April 2012

• Added new transaction type: Balance Inquiry(TRXTYPE=B) can be used to obtain the balance of a pre-paid card.
• Updated TeleCheck chapter: Updated MICR values in Testing TeleCheck Transactions section
• Added TeleCheck Adjustment Response Code Values table
• Updated parameters and examples: Added a description for the response parametersHOSTCODE, RESPTEXT, PROCCARDSECURE, ADDLMSGS and an explanation on how to use these parameters to obtain the processor's raw response codes and response messages.
• Changed the Litle parametersSTREET2,STREET3 toBILLTOSTREET2, BILLTOSTREET3.
• Corrected the description of MERCHSVC parameter for FDMS North, Heartland, Litle, Merchant e-Solutions, Paymentech Salem.
• Updated the examples and removed legacy parameters to include: FIRSTNAME, LASTNAME, STREET, CITY, STATE, ZIP, COUNTRY.
• Updated processor and entity names: Vantiv, previously known as Fifth Third Processing Solutions
• PayPal Australia, previously known as First Data Australia

January 2012

Added new processors:

• First Third International
• Heartland Payment Systems
• Planet Payment
• SecureNet
• TeleCheck
• WorldPay

Added new transaction types:

• TRXTYPE=L can be used to upload credit card data, easing PCI compliance. You can store the resulting PNREF locally for use in performing reference transactions.

Added request parameters:

• ADDLAMTn
• ADDLAMTTYPEn
• AUTHDATE
• CATTYPE
• CONTACTLESS
• CUSTDATA
• CUSTOMERID
• CUSTOMERNUMBER
• DISCOUNT
• DUTYAMT
• DLNAME
• DLNUM
• DOB
• L_ALTTAXAMTn
• L_ALTTAXIDn
• L_ALTTAXRATEn
• L_CARRIERSERVICELEVELCODEn
• L_COMMCODEn
• L_EXTAMTn
• L_PRODCODEn
• L_TAXTYPEn
• ORDERID
• MERCHANTDESCR
• MERCHANTINVNUM
• MERCHANTNAME
• MERCHANTURL
• MERCHANTVATNUM
• MERCHANTZIP
• MISCDATA
• REPORTGROUP
• SILENTTRAN
• STREET3
• VATINVNUM
• VATAXAMT
• VATAXRATE

Added response parameters:

• DUPLICATE (response)
• EXTRMSG (response)

Added concepts:

• Gateway Product Solutions: PayPal Payments Advanced, PayPal Payments Pro, Payflow Pro, Payflow Link
• Transaction Flow
• Transparent Redirect

February 2011

• First publication.

table of contents

Introducing the Gateway Checkout Solutions

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

• About the Gateway Checkout Solutions
• About the Gateway Transaction Flow
• About Security
• Processing Platforms Supporting Card-Present Transactions
• Supported Payment Types
• Recurring Billing Service

About the Gateway Checkout Solutions

Gateway checkout consists of the following solutions:

• Payflow Link
• Payflow Pro
• PayPal Payments Advanced
• PayPal Payments Pro

Summary of the Gateway Checkout Solutions

This is a basic comparison of the Gateway checkout solutions:

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

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

• PayPal Payments Advanced uses web pages hosted by PayPal (also known as* hosted checkout pages*) to send transactions to the PayPal processor. With PayPal Payments Advanced, PayPal is the acquiring bank. By using hosted checkout pages with a secure token, the merchant adheres to compliance rules for handling customer data in a secure way: data is stored on PayPal so that it is not exposed to compromise.

• Like PayPal Payments Advanced, PayPal Payments Pro sends transactions to the PayPal processor and PayPal is the acquiring bank. Using hosted checkout pages is an option. Typically merchants integrate with the Payflow SDK or use HTTPS to send transactions to the PayPal processor.

Note: PayPal strongly recommends that all users of Gateway checkout solutions take advantage of the secure token and the hosted checkout pages. Doing so provides automatic compliance with processing card industry (PCI) standards for protecting cardholder data.

Gateway Product Details

This table compares how the different Gateway checkout solutions support payment processing features.

About the Gateway Transaction Flow

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

1. At your website, the customer clicks Buy to purchase merchandise.
2. You send the transaction request to the Gateway server.
3. The Gateway sends the transaction to the payment processing network.
4. Your processor sends the response back to the Gateway server and processes the transaction (obtains the payment from the customer bank and deposits it in the merchant bank).
5. The Gateway server returns the response to your website.
6. Your website displays the result to the customer.

You can use the core transaction parameters supported by all Gateway processors described in this documentation to send transaction data to your processor. In addition:

• Each Gateway processor may support various additional parameters beyond the core set that you can send in transaction requests.
• Your processor may also support purchasing cards (credit cards employers issue for business-related charges). Purchasing card Level 2 and Level 3 parameters provide specialized reporting so an employer can monitor card use. The parameter information may appear on the customer's statement or describe line items in greater detail. Be sure to check for your processor's Level 2 and 3 parameters in this documentation.

These parameters are listed alphabetically by processor name.

About Security

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

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

Note: PayPal Payments Advanced and Payflow Link merchants are required to use hosted pages.

The Secure Token

The secure token stores request transaction data on the Gateway server. This eliminates the need to resend the parameter data for display in a hosted checkout page where the data might be subject to compromise.

Hosted Checkout Pages

The Gateway enables the use of hosted checkout pages, which help you achieve PCI compliance. The hosted checkout pages enable you to pass transaction data securely to the server and to collect credit card acceptance data.

Note: You are required to use hosted pages with PayPal Payments Advanced and Payflow Link.

The following figure shows the transaction flow when using hosted pages and a secure token.

Figure legend:

1. The customer clicks Buy to purchase merchandise on your website.
2. You request a secure token by passing a token ID to the Gateway server.
3. The Gateway server returns the secure token and your token ID to your website.
4. You submit the secure token and token ID in an HTTP post to pages hosted on the Gateway server and redirect the customer's browser to the hosted pages.
5. The Gateway server uses the secure token to retrieve the amount and other transaction data. The customer submits their credit card number, expiration date, and other sensitive data directly to the host pages rather than to your website, easing your PCI compliance requirements.
6. The Gateway processes the payment through the payment processing network.
7. The Gateway server transparently returns the customer to the location on your website that you specified in the request to obtain a secure token. You display the results to the customer on your website.

Note: If you do not get a response from the Gateway server, submit an Inquiry transaction, passing in the secure token to see if the transaction has completed. For details, see Submitting Inquiry Transactions.

PCI Compliance Without Hosted Pages - Transparent Redirect

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

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

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

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

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

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

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

  Note: To ensure that the post goes from the browser directly to PayPal and not back to your website, you should add scripting.

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

• The Gateway server transparently sends the customer to the location on your website that you specified in the request to obtain a secure token. You display the results to the customer on your website.

The PayPal Manager Website

Payflow merchants can manage their Payflow account settings, view reports, and perform transactional processing on the Payflow Manager website: https://manager.paypal.com/.

For assistance with using the Payflow Manager website, refer to the online help.

Note: PayPal Payments Advanced and PayPal Payments Pro merchants should also use the Payflow Manager website (https://manager.paypal.com/) to perform transactional processing functions instead of the main paypal.com website. However, the main paypal.com website can be used to process chargebacks or other non-transactional items.

Processing Platforms Supporting Card-Present Transactions

The following processing platforms support card-present transactions.

For instructions on setting up or changing your processor, see the Processor Setup Guide PDF.

Note: PayPal Australia (FDRA) merchants with a 12-digit merchant ID, can contact Payflow support to request a 16-digit merchant ID.

• American Express
• American Express APAC
• Elavon
• First Data Merchant Services (FDMS) Nashville
• First Data Merchant Services (FDMS) North
• First Data Merchant Services (FDMS) South
• Global Payments Central
• Global Payments East
• Heartland Payment Systems
• Litle
• Merchant e-Solutions
• Moneris Solutions
• Paymentech Salem
• Paymentech Tampa
• PayPal
• Planet Payment
• SecureNet
• TeleCheck
• TSYS Acquiring Solutions
• Vantiv
• WorldPay

Supported Payment Types

• Credit cards
• PayPal (supported by PayPal's Express Checkout product)
• Pinless debit cards
• Electronic checks
• Check cards
• Purchasing cards (also referred to as commercial cards, corporate cards, procurement cards, or business cards) Level 2 and Level 3
• Automated Clearing House (ACH). For information on performing ACH transactions, contact your PayPal Sales Representative.

Supported Languages

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

Recurring Billing Service

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

You enroll separately for the Recurring Billing Service. You can learn about the Recurring Billing Service in the Payflow Recurring Billing Service user's guide. If you already have this service - this user guide will show you how to define and manage recurring transactions programmatically. You can also manage Recurring Billing tasks in PayPal Manager.

Fraud Protection Services

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

You enroll separately for Fraud Protection Services. You can learn more about Fraud Protection Services in the Payflow Fraud Protection Services User's Guide. If you already have this service - this user guide will show you how to set up Fraud Protection filters. You can also manage some aspects of your Fraud Protection Services in PayPal Manager.

table of contents

Secure Token

This section describes the secure token.

• About the Secure Token
• Integrating the Secure Token With the Hosted Checkout Pages
• Integrating the Secure Token Without the Hosted Checkout Pages - Transparent Redirect
• Posting to the Hosted Checkout Page
• Using the PARMLIST Parameter

Important: Use only the Payflow parameters described in this guide with the Secure Token. If you are using the legacy Payflow Link HTML input tag integration, refer to the Payflow Link User's Guide for information on legacy Payflow Link features supported by your integration.

About the Secure Token

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

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

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

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

Note: You cannot modify the data sent with a secure token, with one exception. You can configure PayPal Manager to allow you to modify billing and shipping information.

Integrating the Secure Token With the Hosted Checkout Pages

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

Note: The secure token is valid for 30 minutes, and you can only use it one time. If you attempt to use the token after the time limit has expired, your transaction will fail with Result value 7, "Secure Token Expired." If you attempt to reuse the token, you receive an error.

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

SECURETOKENID=9a9ea8208de1413abc3d60c86cb1f4c5

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

CREATESECURETOKEN=Y

Secure Token Example

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

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

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

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

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

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

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

Note: The secure token is valid for 30 minutes, and you can only use it one time. If you attempt to use the token after the time limit has expired, your transaction will fail with Result value 7, "Secure Token Expired." If you attempt to reuse the token, you receive an error.

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

SECURETOKENID=9a9ea8208de1413abc3d60c86cb1f4c5

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

CREATESECURETOKEN=Y

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

SILENTTRAN=TRUE

Transparent Redirect Example

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

TRXTYPE=A&BILLTOSTREET=123 Main St.&BILLTOZIP=95131&AMT=24.35&INVNUM=INV12345&PONUM=PO12345&CURRENCY=USD
&CREATESECURETOKEN=Y&SECURETOKENID=9a9ea8208de1413abc3d60c86cb1f4c5&SILENTTRAN=TRUE

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

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

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

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

If you are using the PARMLIST parameter with the Transparent Redirect, see Using the PARMLIST Parameter for more information.

Secure Token Errors

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

A Payflow Secure Token will expire:

• If the same Secure Token is passed to Payflow a total of 3 times.
• 30 minutes after the Secure Token was generated.
• When the token is used in a successful transaction.

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

• 160. Secure Token already been used. Indicates that the secure token has expired due to either a successful transaction or the token has been used three times while trying to successfully process a transaction. You must generate a new secure token.

• 161. Transaction using secure token is already in progress. This could occur if a customer hits the submit button two or more times before the transaction completed.

• 162. Secure Token Expired. The time limit of 30 minutes has expired and the token can no longer be used.

If you see a different error code in the RESULT parameter, refer to the RESULT Values and RESPMSG Text section for more information.

Posting to the Hosted Checkout Page

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

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

https://payflowlink.paypal.com

Send the following parameter data:

• SECURETOKEN returned in the transaction response
• SECURETOKENID

HTTP Form Post Examples

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

<html>
 <head>
  <title>PageTitle</title>
 </head>
 <body>
  <form method="post" action="https://payflowlink.paypal.com">
   <input type=hidden value="Fj+1AFUWft0+I0CUFOKh5WA==" name=SECURETOKEN/>
   <input type=hidden value="9a9ea8208de1413abc3d60c86cb1f4c5" name=SECURETOKENID/>
  </form>
 </body>
</html>

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

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

<html>
 <head>
  <title>PageTitle</title>
 </head>
 <body>
  <form method="post" action="https://payflowlink.paypal.com">
   <input type="text" name="SECURETOKEN" value="FvwEnHTYRNUSVsZRlhFpudA=="/>
   <input type="text" name="SECURETOKENID" value="9a9ea8208de1413abc3d60c86cb1f4c5"/>
   <input type="hidden" name="PARMLIST" value="INVNUM[8]=INV123&AMT[5]=25.50&CURRENCY[3]=USD"/>
   <input type="submit"/>
  </form>
 </body>
</html>

table of contents

Configuring Hosted Checkout Pages

This chapter describes the following:

• Configuring Hosted Pages Using PayPal Manager
• Using a Secure Token to Pass Hosted Pages Customization Parameters
• Hosted Pages and Mobile Browsers
• Silent Posts
• Passing Other Data to Your Server Using Post or Silent Post

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

Note: The Payflow Gateway implementation helps to achieve PCI compliance but does not necessarily guarantee it.

There are two ways to configure hosted checkout pages:

• Configuring Hosted Pages Using PayPal Manager — Logging in to PayPal Manager and making selections.
• Using a Secure Token to Pass Hosted Pages Customization Parameters — Using a secure token and passing configuration parameters in a form post

Configuring Hosted Pages Using PayPal Manager

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

• Setup
• Customize
• Integrate

Setup

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

You can perform tasks such as:

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

• Determine the cancel URL and the text of the link the buyer clicks on to cancel the payment on your website. The cancel URL is the page to which PayPal redirects the buyer's browser if the buyer does not approve the payment.

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

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

• Choose to display a PayPal hosted payment confirmation page or host your own confirmation page on your website. You can also specify the paypal hosted confirmation page header and footer text and the URL and text for the return link. Additionally, you can choose to enable the silent post feature.

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

For complete details on these settings, click the Help button on the Setup page. To quickly get started with your hosted pages, go to the Hosted Pages Getting Started Guide on the PayPal developer portal. For more information on the Silent Post feature, see Silent Posts.

Customize

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

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

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

• Preview - Preview the changes you have made to your layout before saving and publishing it
• Save and Publish - Save all the changes you have made and publish the updated layout. Your buyers will see the updated payment page.
• Cancel - Discard all the changes you have made in this session.
• Undo Changes - Discard all changes you have made since the last time you saved the layout. Your buyers will see the last saved layout.

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

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

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

Note: These customizations are not applied to the mobile version of the hosted checkout pages.

• Header (Applicable to Layouts A and B) - You can change the following:
  • Header height (Applicable to Layouts A and B)
  • Header background color (Applicable to Layout B only)
  • Header font type, size (Applicable to Layouts A and B)
  • Header font color (Applicable to Layout B only)
  • Swap between displaying the business name or the business logo image
  • Edit business name in the header (Applicable to Layouts A and B)
  • Position of the business name or the logo within the header (left, centered, right) (Applicable to Layouts A and B)
• Page Background (Applicable to Layout B only) - You can change the following:
  • Background color
  • Footer text color
  • Upload a background image - .jpg, .jpeg, .gif, or .png. The maximum allowable image size is 100kb.
  • Repeat image option
• Payment Method Section (Applicable to Layouts B and C) - You can change the following:
  • Text color of the section title (Applicable to Layout B only)
  • Subheader text color (Applicable to Layouts B and C)
  • Color of other text in this section (Applicable to Layout B only)
  • Section border color (Applicable to Layouts B and C)
  • Button color and button text color (Applicable to Layouts B and C)
• Order Summary Column (Applicable to Layout B only) - You can change the following:
  • Column background color
  • Upload a background image
  • Repeat image option

Integrate

See the Testing with the Payflow Gateway guide. This guide shows you how to set up a test account, configure a hosted checkout page, and submit a test transaction.

Additional Resources

The PayPal developer portal includes:

• Developer integration guides which are comprehensive product guides like this guide.
• See the Payflow Gateway product page for links to other useful resources such as SDKs, screencasts, code samples, and more.

Using a Secure Token to Pass Hosted Pages Customization Parameters

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

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

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

Setup Parameters

Customize Parameters

Other HTML Post Parameters

Using the PARMLIST Parameter

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

PARMLIST Example

<html>
 <head>
   <title>PageTitle</title>
 </head>
 <body>
  <form method="post" action="https://payflowlink.paypal.com">
   <input type="hidden" name="SECURETOKEN" value="Fj+1AFUWft0+IOCUFOKh5WA==" />
   <input type="hidden" name="SECURETOKENID" value="9a9ea8208de1413abc3d60c86cb1f4c5" />
   <input type="hidden" name="PARMLIST" value="INVNUM=INV1234&AMT=25.50&CURRENCY=USD &PONUM=PO12345" />
   </form>
 </body>
</html>

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

Note: The MODE parameter is deprecated. If you are using a test secure token, instead of passing MODE=TEST, change the Form Action attribute value to the testing URL: https://pilot-payflowlink.paypal.com.

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

Hosted Pages and Mobile Browsers

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

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

Mobile Optimized Checkout Pages

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

The TEMPLATE form post parameter

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

Mobile page flow for a PayPal payment

Mobile page flow for a credit card payment

Silent Posts

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

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

• Go to Service Settings, then from the Hosted Checkout Pages section select Setup
• On the Setup page, set Use Silent Post to Yes. Then enter the Silent Post URL on your server.

Note: To ensure that transactions proceed only if your script actually receives the data returned by the Silent Post, you must Force Silent Post Confirmation by checking Void transaction when my server fails to receive data sent by the silent post.

Force Silent Post Confirmation

The Force Silent Post Confirmation feature ensures that no transactions proceed unless your Web site receives the Silent Post data. If you enable this feature, Payflow Gateway sends the Silent Post data and waits for a 200 OK from your server (indicating the server's receipt of the data). If Payflow Gateway does not receive the success response, then the transaction is voided and the customer sees a communication error message. In this case, PayPal Manager displays both a transaction that succeeded and a transaction that was voided. To select this feature, be sure to check Void transaction when my server fails to receive data sent by the silent post when setting up Silent Posts in PayPal Manager.

Passing Other Data to Your Server Using Post or Silent Post

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

Note: USER1 through USER10 are not displayed to the customer and are not stored in the PayPal transaction database.

table of contents

Payflow SDK

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

• Preparing the Payflow Gateway Client Application.
• Activating Your Payflow Gateway Account.
• Host URL Addresses

Note: Each SDK includes full API documentation.

Important: The Payflow SDK is available as a .NET or Java library. Using these SDKs is recommended to simplify integration. Alternately you can build your own API by posting transactions directly to the Gateway servers using HTTPS. See Posting Transactions Directly Without the Payflow SDK for more information.

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

Preparing the Payflow Gateway Client Application

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

• Download the Payflow SDK.
  • From the SDKs Downloads page, download the Payflow SDK appropriate for your platform.
• Extract the files to a local directory.
• Configure your firewall.
  • If you have a stateful firewall, enable outbound traffic for HTTPS (port 443). The firewall keeps state on the connection, and automatically permits the inbound response from PayPal.
  • If you do not have a stateful firewall, enable inbound and outbound traffic for HTTPS (port 443). Outbound traffic permits the initial Gateway request, while inbound permits the response from PayPal.
• Read the Readme.txt file.
  • The Readme.txt file includes integration information and samples that illustrate how to use the client application in your development environment.

Activating Your Payflow Gateway Account

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

• Log in to PayPal Manager at https://manager.paypal.com
• Click ActivateYour Account and follow the on-screen instructions.
• Change the URL within your web or desktop application to point to the live Gateway server host addresses.

Host URL Addresses

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

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

Note: If you are using an older version of the SDK, you will notice that the live and testing URLs have changed. Be sure to use the URLs mentioned above and remove the "/transaction" from the end of the URL.

Testing Your PayPal Payments Advanced and PayPal Payments Pro Integration

If you have a PayPal Payments Advanced or a PayPal Payments Pro account and you would like to use the testing URL to test your integration, follow the steps outlined in this PayPal Knowledge Base article.

Note: If you would like to test a Payflow Express Checkout transaction, follow steps one through three outlined in the above-mentioned knowledge base article. In addition, be sure to do the following:

• In the PayPal Sandbox, create a buyer account and add a positive balance to the account. See creating Sandbox accounts for more information.
• Send all test transaction requests as POSTs to the Payflow testing host address: https://pilot-payflowpro.paypal.com.
• Send Express Checkout redirects to: https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-Token. You must be logged into the Sandbox before redirecting.

Passing Information to and Receiving Information from the Hosted Pages

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

• For live transactions, use https://payflowlink.paypal.com
• For testing purposes, use https://pilot-payflowlink.paypal.com

Note: The MODE parameter for passing a test secure token is deprecated. Instead, post your form parameters to the testing Payflow Link URL.

table of contents

Sending a Simple Transaction to the Server

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

• About Name-Value Pairs
• Payflow Connection Parameters
• User Parameter Data
• Sale Transaction Example
• Formatting Payflow Gateway Transactions

About Name-Value Pairs

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

PARAMNAME=value

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

PARAM1NAME=value&PARAM2NAME=value&PARAM3NAME=value

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

Using Special Characters In Values

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

The following are invalid:

COMPANYNAME=Ruff & Johnson

COMMENT1=Level=5

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

COMPANYNAME[14]=Ruff & Johnson

COMMENT1[7]=Level=5

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

Name-Value Parameter Syntax Guidelines

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

• Do not use spaces in values.
• Do not place quotation marks within the body of the NVP parameter string.
• Separate all NVPs using an ampersand (&).
• Set the VERBOSITY transaction parameter to HIGH to have the response return detailed information. Act upon the returned values that you need for the transaction.
• If you duplicate a parameter in your NVP string, the last item will always be the one used and the others will be discarded.

Do Not URL Encode Name-Value Parameter Data

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

This example is incorrect:

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

This example is correct:

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

Payflow Connection Parameters

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

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

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

User Parameter Data

All Gateway transactions require the user parameters described as follows.

User parameters

Sale Transaction Example

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

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

• TRXTYPE - The type of the transaction, such as S for Sale
• TENDER - The method of payment, such as C for credit card
• ACCT - The buyer's credit card number
• AMT - The amount of the sale, including two decimal places and without a comma separator
• EXPDATE - The expiration date of the credit card

Typical Sale Transaction

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

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

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

When the transaction completes, the Gateway server returns a response string made up of name-value pair response parameters. If the transaction is successful, the Payflow Gateway server returns a RESULT parameter with the value 0. The value of the PNREF parameter is the transaction ID, which helps to identify the transaction in future requests; the RESPMSG parameter is a string indicating whether the transaction was approved.

The following is an example response:

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

Formatting Payflow Gateway Transactions

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

table of contents

Submitting Credit Card Transactions

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

Note: Some of the transaction types and features described in this chapter are not supported by all processors. Be sure to check with your processor for information on the specific functionality that is supported.

• Obtaining an Internet Merchant Account
• About Credit Card Processing
• Credit Card Features
• Planning Your Gateway Integration
• Core Credit Card Parameters
• Submitting Account Verifications
• Submitting Authorization - Delayed Capture - Transactions
• Submitting Balance Inquiry Transactions
• Submitting Card Present SWIPE Transactions
• Submitting Credit Refund Transactions
• Submitting Inquiry Transactions
• Submitting Partial Authorizations
• Submitting Purchasing Card Transactions
• Submitting Rate Lookups
• Submitting Reference Transactions Tokenization
• Submitting Sale Transactions
• Submitting Soft Merchant Information
• Submitting Voice Authorization Transactions
• Submitting Void Transactions
• Using Address Verification Service
• Using Card Security Code
• Information for the PayPal Acquirer

Obtaining an Internet Merchant Account

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

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

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

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

About Credit Card Processing

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

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

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

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

Note: For card-not-present transactions, such as, online transactions, merchants are required to provide a service or ship goods before or on the same day the transaction is captured.

Credit Card Features

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

Note: Even though the Payflow Gateway does not charge fees for certain transactions, your processor, including PayPal as your merchant bank, may charge a fee.

The Payflow SDK also supports the following credit card features:

• Address verification service and card security code validation
• Card-present (SWIPE) transactions
• Partial authorizations for pre-paid cards
• Purchasing card transactions
• Reference transactions (also called tokenization)
• Submitting Soft Merchant information

Planning Your Gateway Integration

When designing your Gateway integration, evaluate whether to use:

• A one-step or two-step transaction process:

  • One-step: Submit a sale transaction, which performs the authorization and (if successful) then flags the transaction for settlement.

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

  According to card association rules, most physical goods merchants should use a two-step process, since settlement should occur when the merchant ships the goods. A two-step process is also useful for evaluating information in the response, such as whether the issuer verifies the billing address, and so on. Electronic goods merchants, who fulfill the order immediately, can use the one-step process. Check with your Internet Merchant Account provider for suggestions on the best method for you.

• Risk management tools such as address verification service and card security code. For the address verification service, if the initial transaction submits the data, the issuer checks the street address and the zip code against the billing address on file for the consumer.

  Card security code refers to a three- or four-digit number that appears on the back of most credit cards. On American Express, the number appears proceeding and to the right of the embossed card number. Card security code is known by other names, such as CVV2, depending on the type of card. If card security code data is submitted, the issuer can notify you whether the number matches the number assigned to the card. It may also be possible to implement additional safeguards yourself or to use a fraud service. You might want to discuss risk management with your Internet Merchant Account provider.

• Your local database or PayPal Manager reports to store and manage the data. You may want to store shipping information in your system or you may prefer to send the information to PayPal with the transaction and report on it later.

  Note: Consider whether and how to use COMMENT1 and COMMENT2 to help tie reports to your orders/customers or to report on other information about the transaction.

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

• Your internet Merchant Acquirer practices to get the most advantageous rates.

Complying With E-commerce Indicator

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

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

Handling Credit Card Type Information

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

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

Note: American Express cards require explicit acceptance when PayPal is the processor. To accept American Express cards, go to the Profile Page in PayPal Manager and click American Express card acceptance.

Core Credit Card Parameters

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

Note: See PayPal Credit Card Transaction Request Parameters for the request parameters specific to the PayPal Processor.

Echoing data back

The ECHODATA field is a Payflow request parameter. Use this field if you would like some of your request field values echoed back to you in the response. The following ECHODATA field values can be used for POST or Silent Post transactions.

Submitting Account Verifications

Account verifications, also known as zero-amount authorizations, are used for verifying the validity of customer credit card information. TRXTYPE=A is required for both account verifications and for normal authorization transactions; however, account verifications are different from normal authorizations in the following ways:

• For account verifications, pass a zero AMT. If you pass any other amount, the transaction becomes a normal authorization that places a hold on the cardholder's open-to-buy limit.
• In account verifications, even if the RESULT value returned is 0 (Approved), the RESPMSG value returned is Verified instead of Approved.

Note: Payflow returns RESULT value 4, Invalid Amount, if the processor does not support account verifications.

See the Account Verifications Supported Credit Cards by Processor table for details.

When To Use Account Verifications

Use account verifications to validate account numbers and other authentication elements such as CVV2 and AVS.

Account verifications cannot be voided, captured, or refunded. Attempting to do so results in a declined transaction, RESULT=12.

A reference transaction can be based on a successful account verification transaction and used to charge the customer's verified account. See Submitting Reference Transactions Tokenization.

Required Account Verification Parameters

To perform an account verification, pass the following parameters:

Example Account Verification String

The following is an example of account verification:

TRXTYPE=A&TENDER=C&PARTNER=PayPal&USER=SuperUser&PWD=SuperUserPassword&AMT=0.00&ACCT=378282246310005
&EXPDATE=1215&INVNUM=PONUM1&VERBOSITY=HIGH&BILLTOZIP=95031

This is the response:

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

Account Verifications Supported Credit Cards by Processor

The following table lists the credit cards for which each processor supports account verifications.

Submitting Authorization - Delayed Capture - Transactions

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

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

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

Note: PayPal Payments Advanced and Payflow Link merchants cannot submit authorization transactions unless they use the hosted checkout pages.

When to Use Authorization - Delayed Capture - Transactions

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

Note: If you signed up for the PayPal processor with Fraud Protection Services, use delayed capture processing for all sale transactions.

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

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

Required Authorization Transaction Parameters

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

Submitting Balance Inquiry Transactions

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

Note: Payflow returns RESULT value 3, Invalid Transaction Type, if the processor does not support balance inquiry.

Processing Platforms Supporting Balance Inquiry Transactions

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

• WorldPay

Required Balance Inquiry Parameters

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

Example Balance Inquiry Transaction String

The following is an example of a balance inquiry transaction:

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

This is the response:

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

Submitting Card Present - SWIPE - Transactions

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

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

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

• Contact your merchant account provider to make sure that they support card-present transactions.
• Contact PayPal Customer Service to request them to set up your account properly for accepting and passing swipe data.
• If you plan to process card-present as well as card-not-present transactions, set up 2 separate Gateway accounts. Request that one account be set up for card-present transactions, and use it solely for that purpose. Use the other for card-not-present transactions. Using the wrong account may result in downgrades.
• A sale is the preferred method to use for card-present transactions. Consult with your acquiring bank for recommendations on other methods.

Processing Platforms Supporting Card-Present Transactions

The following processing platforms support card-present transactions.

For instructions on setting up or changing your processor, see the Processor Setup Guide PDF.

Note: PayPal Australia (FDRA) merchants with a 12-digit merchant ID, can contact Payflow support to request a 16-digit merchant ID.

• American Express
• American Express APAC
• Elavon
• First Data Merchant Services (FDMS) Nashville
• First Data Merchant Services (FDMS) North
• First Data Merchant Services (FDMS) South
• Global Payments Central
• Global Payments East
• Heartland Payment Systems
• Litle
• Merchant e-Solutions
• Moneris Solutions
• Paymentech Salem
• Paymentech Tampa
• PayPal
• Planet Payment
• SecureNet
• TeleCheck
• TSYS Acquiring Solutions
• Vantiv
• WorldPay

Card Present Transaction Syntax

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

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

Note: Do not include the ACCT or EXPDATE parameters in card-present transactions. The SWIPE value includes this data.

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

Submitting Refund Transactions

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

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

Required Credit Transaction Parameters

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

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

Non-Referenced Credits Not Allowed

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

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

Non-Referenced Credits Allowed

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

• ACCT
• EXPDATE
• AMT

Note: The default security setting for Gateway accounts is Allow non-referenced credits = No. Sending the ORIGID is the preferred method for performing credit transactions, as described in Non-Referenced Credits Not Allowed. Using the acct, expdate or amt parameters for such restricted accounts leads to the return of result value 117 failed the security check. To help reduce fraud, PayPal recommends that you do not activate non-referenced credits unless you have a business reason. For information on configuring your security settings, see PayPal Manager online help.

Refund Example

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

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

Fields Copied From the Original Transaction Into the Credit Transaction

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

Note: These fields are not copied for referenced credits: TAXAMT, TAXEXEMPT, DUTYAMT, FREIGHTAMT, and (for American Express only) DESC4.

Note: For processors that use the RECURRING parameter: If you set the RECURRING parameter to Y in the original transaction, this setting is ignored when forming the credit transaction.

Submitting Inquiry Transactions

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

When To Use an Inquiry Transaction

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

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

Required Parameters When Using the PNREF

To perform an inquiry, pass the following parameter:

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

Inquiry Transaction Parameter String Using the PNREF

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

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

Required Parameters When Using the CUSTREF

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

Note: If there are multiple transactions with a particular CUSTREF value, inquiry returns the last transaction only with the specified CUSTREF. To make sure that you can always access the correct transaction, use a unique CUSTREF when submitting any transaction, including retries.

Inquiry Transaction Parameter String Using the CUSTREF

This is an example inquiry parameter string using the CUSTREF.

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

Required Parameters When Using the Secure Token

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

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

Inquiry Parameter String Using the Secure Token

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

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

The following is the response string.

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

Submitting Partial Authorizations

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

When To Use Partial Authorizations

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

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

You can take either of the following actions:

• Accept the $80.00 and ask the buyer to provide an alternate payment for the additional $20.00.
• Reject the partial authorization and submit to the card issuer an authorization reversal (Void) for $80.00.

Required Partial Authorization Parameters

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

Example Partial Authorization

The following is an example partial authorization.

• You submit the initial authorization as a partial authorization.
  TRXTYPE=A&TENDER=C&AMT=100.00&ACCT=4111111111111111&EXPDATE=0119
&PARTIALAUTH=Y&VERBOSITY=HIGH
• The card issuer notes that the card has a remaining balance of $80.00.
• The card issuer sends a partial authorization for $80.00.
  RESULT=0&PNREF=VRNS1A3B33C9&RESPMSG=Partial Approval&AUTHCODE=11111&HOSTCODE=E&PROCAVS=U
&TRANSTIME=2010-04-21 11:30:45&AMT=80.00&ORIGAMT=100.00&BALAMT=0&ACCT=1111&EXPDATE=0119&IAVS=X
RESPMSG is Partial Approval, AMT is now the actual amount approved, ORIGAMT is the original requested amount, and BALAMT is the balance on the card.
  Since the amount charged is greater than the amount available on the card, the response sets the balance amount (BALAMT) to zero. If BALAMT is zero, check if there is a balance due by comparing the original amount (ORIGAMT) to the amount charged (AMT).
  You can choose to perform one of the following tasks:
• Accept the $80.00 and request an alternate payment from the buyer for the additional $20.00.
• Reject the partial authorization by sending the card issuer an authorization reversal (void) for $80.

Submitting Purchasing Card Transactions

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

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

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

Submitting Reference Transactions - Tokenization

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

The PNREF returned in the original transaction is valid for use in reference transactions for 12 months and possibly up to 15 months.

For transactions processed by the PayPal processor, use the PPREF returned in the original transaction as the transaction ID, instead of the PNREF.

When To Use a Reference Transaction

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

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

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

Note: When the Gateway looks up the reference transaction, it does not alter in any way the transaction referenced or any other transaction in the database. A reference transaction is a read-only operation. Payflow populates with data and acts upon the new transaction only. It does not maintain any linkage between the reference transaction and the new transaction.

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

Transaction Types That Can Be Used As the Original Transaction

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

• Authorization (To capture the funds for an approved authorization transaction, be sure to perform a delayed capture transaction, not a reference transaction.)
• Credit
• Delayed capture
• Sale
• Voice authorization (Payflow does not copy the voice authorization code to the new transaction)
• Void

Fields Copied From Reference Transactions

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

Example Reference Transaction

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

This example procedure creates a reference transaction:

Submit the initial transaction, such as an authorization. You use an authorization transaction for the full amount of the purchase of $100 as shown in this transaction request:

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

Note the value of the PNREF in the response:

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

Note: The PNREF returned in the original transaction is valid in reference transactions for 12 months and possibly up to 15 months.

If the original transaction was processed by the PayPal processor, pass either the PPREF or PNREF of the original transaction in the ORIGID parameter.

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

TRXTYPE=D&PWD=x1y2z3&PARTNER=PayPal&VENDOR=SuperMerchant
&USER=SuperMerchant&ORIGID=VXYZ01234567&AMT=66.00

The following is the response:

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

Note: The TENDER parameter is not required in this step. The TENDER of the capture will be the same as that of the original transaction.

Submit a new sale transaction or an authorization and delayed capture transaction of $34 for the rest of the shipment. When you ship the remainder of the product, you can collect the remaining $34 in a sale transaction that uses the initial authorization as a reference transaction. (This is a sale transaction because Payflow allows only one delayed capture transaction per authorization.)

The following is a sale transaction request:

TRXTYPE=S&TENDER=C&PWD=x1y2z3&PARTNER=PayPal&VENDOR=SuperMerchant
&USER=SuperMerchant&ORIGID=VXYZ01234567&AMT=34.00

The following is the response:

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

Note: If the original transaction was processed by the PayPal processor, pass either the PPREF or PNREF of the original transaction in the ORIGID parameter. Also, if the original transaction was created using Express Checkout or a Billing Agreement, set the TENDER parameter to TENDER=P.

Data Upload - Storing Credit Card Data on the Gateway Server

To facilitate creating reference transactions while assisting you with PCI compliance, PayPal allows you to upload credit card data by submitting an upload transaction (TRXTYPE=L). At minimum, you must pass values for the following parameters:

• TRXTYPE
• TENDER
• ACCT
• EXPDATE

This is an example upload transaction request:

TRXTYPE=L&TENDER=C&ACCT=5105105105105100&EXPDATE=1215&BILLTOFIRSTNAME=Ted
&BILLTOLASTNAME=Smith&BILLTOSTREET=123&BILLTOCITY=SanJose&BILLTOSTATE=CA
&BILLTOZIP=12345&BILLTOPHONENUM=123-123-1234

This is the response:

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

You can send shipping and billing information to be stored, but you must not include the AMT field. If you pass a value for AMT, you will receive an error with RESULT=4 and RESPMSG=Invalid Amount.

Note: PayPal does not verify the credit card data, as it is not sent to the banks for processing. To validate a transaction, you must submit an account verification, also known as a zero dollar authorization (TRXTYPE=A). For details, see Submitting Account Verifications.

Submitting Sale Transactions

The sale transaction (TRXTYPE=S) charges the specified amount against the account, and marks the transaction for immediate fund transfer during the next settlement period. PayPal submits each merchant's transactions for settlement on a daily basis.

Note: PayPal Payments Advanced and Payflow Link users cannot submit sale transactions unless they use the hosted checkout pages.

When To Use a Sale Transaction

A sale transaction is best suited to businesses that provide immediate fulfillment for their products or services. If your business does not provide immediate fulfillment, credit card association rules recommend that you use an authorization and a delayed capture transaction. For details, see Submitting Authorization - Delayed Capture - Transactions. To recharge a credit card when you are not storing the credit card information in your local database, you can perform a new reference transaction based on a Sale transaction.

Note: PayPal Payments Advanced and PayPal Payments Pro merchants using Fraud Protection Services (FPS) should process their transactions as Authorizations with Delayed Capture instead of a Sale. FPS transactions are treated as authorizations and if the transaction is submitted as a Sale, Payflow auto-captures such transactions approximately every two hours, which may result in a 2-hour or more delay in settling the transaction.

Additional Parameters For Sale Transactions

To perform a sale transaction, pass the following parameters:

• ACCT
• AMT
• EXPDATE

Note: The pinless debit tender type requires essentially the same parameters as a credit card transaction. In addition to the values required by all transactions, pass values for the ACCT and AMT parameters. The First Data Merchant Services (FDMS) South processing platform supports sale and credit transactions only.

Typical Sale Transaction Parameter String

The following is a typical NVP string passed in a sale transaction.

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

Besides the required parameters that you pass in a sale transaction, this string includes other typical parameters. The COMMENT1 (and COMMENT2) fields help to track transaction information. Pass the customer's street address (BILLTOSTREET) and zip code (BILLTOZIP) to use address verification service. To validate card security codes, pass the CVV2 parameter. For details on address verification service and card security code, see the following:

• Submitting Card Present SWIPE Transactions
• Using Card Security Code

Submitting Soft Merchant Information

Soft merchant information is detailed data about a merchant such as the merchant's name, business address, business location identifier, and contact information.

About Soft Merchant Information

Merchants aggregators, who perform transactions on behalf of other merchants under a single merchant account, provide the processor with soft merchant information. Soft merchant information identifies the merchant making the sale and includes information about that merchant on the buyer's card statement.

Say, for example, Outdoor Apparel has a chain of 12 stores located in the Western United States with the corporate office in Oakland, California. John Lui purchases a pair of hiking boots online from Hiker's Duds in San Jose, California, and charges them to his credit card. The transaction goes to the aggregator at Outdoor Apparel in Oakland. The aggregator sends soft merchant information about the Hiker's Duds store with the transaction to the credit card processor. When John receives his credit card statement, he recognizes the charge for the hiking boots he purchased at Hiker's Duds in San Jose.

Ways to Send Soft Merchant Information

There are 2 ways you can send soft merchant information:

• Soft merchant information (SM Record)
• Merchant descriptor (M Record)

The Paymentech processor requires that you follow their guidelines to send soft descriptor information using either of these methods.

Soft Merchant Information - SM Record

Soft merchant information is for American Express credit cards only. Typically aggregators (and petroleum merchants) pass soft merchant information to the processor in Gateway parameter fields such as the following:

• MERCHANTNAME
• MERCHANTSTREET
• MERCHANTCITY
• MERCHANTSTATE
• MERCHANTNAME
• MERCHANTZIP
• MERCHANTCOUNTRYCODE
• MERCHANTLOCATIONID
• MERCHANTID
• MERCHANTCONTACTINFO

Note: Paymentech Salem processor only: To take advantage of this level of soft descriptor, you must be approved by the Paymentech Risk/Credit department. Upon approval, Paymentech sets a flag at the transaction division to enable you to send the preceding parameters. If the flag is not set and you send the parameters, your transaction is rejected with Error 258.

Merchant Descriptor - M Record

A merchant descriptor defines the merchant name and product that appears on the account holder's statement. The descriptor information is passed to the processor in parameter fields such as the following:

• MERCHDESCR - Defines the merchant name and product
• MERCHSVC - Includes the merchant contact information such as the merchant's telephone number, e-mail address, or website URL

To use merchant descriptors, you are not required to have the processor set the division level flag. However, you are required to obtain prior risk or credit department approval before sending the parameters.

Note: M Record information (merchant soft descriptor information) is also supported for the PayPal processor.

Submitting Voice Authorization Transactions

A voice authorization (TRXTYPE=F) is a transaction that the processing network authorizes over the phone.

Note: The PayPal processor does not support voice authorization transactions.

When To Use a Voice Authorization Transaction

Some transactions cannot be authorized over the Internet (for example, high dollar amounts) and require manual authorization. These referral transactions generate RESULT value 13.

In these situations, you contact the customer service department of your merchant bank and provide the payment information as requested. If the bank approves the transaction, the bank provides you with a voice authorization code (AUTHCODE) for the transaction.

On approval, a voice authorization transaction is treated like a sale transaction and is settled with no further action on your part.

Like sale transactions, you can void approved voice authorizations before settlement occurs.

Required Voice Authorization Transaction Parameters

To perform a voice authorization transaction, pass the AUTHCODE provided by your merchant bank.

The following is an example Voice Authorization request parameter string:

TRXTYPE=F&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant
&PWD=x1y2z3&AUTHCODE=AB3456&ACCT=5555555555554444&EXPDATE=1215&AMT=123.00&VERBOSITY=HIGH

Submitting Void Transactions

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

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

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

When To Use a Void Transaction

Use the following guidelines when using void transactions:

• You can void delayed capture, sale, credit, authorization, and voice authorization transactions. You cannot void a void transaction.
• You can only use a void transaction on a transaction that has not yet settled. To refund a customer's money for a settled transaction, submit a credit transaction.

Required Void Transaction Parameters

To perform a void transaction, you are required to pass the following parameter:

Fields Copied From the Original Transaction Into the Void Transaction

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

Note: For processors that use the RECURRING parameter: If you set the RECURRING parameter to Y in the original transaction, the setting is ignored when forming the void transaction.

Example Void Transaction Parameter String

The following is an example void transaction string:

TRXTYPE=V&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant
&PWD=x1y2z3&ORIGID=VPNE12564395&VERBOSITY=HIGH

Submitting Rate Lookups

The currency conversion rate lookup transaction (TRXTYPE=K) supports basic Multi-Currency Pricing (MCP). The MCP feature enables you to accept payments in multiple currencies.

Note: Currently, this feature is only supported by the Planet Payment processor. Contact the processor for a list of supported currencies.

When To Use a Rate Lookup

A rate lookup transaction (TRXTYPE=K) performs a currency conversion rate lookup used for a subsequent Multi-Currency Pricing (MCP) transaction. Merchants can take advantage of this feature to charge buyers for purchases in the buyer's local currency.

In the rate lookup request, pass the target CURRENCY code and the AMT you would like converted. A RATELOOKUPID is returned in the response. In order to charge the buyer with the currency specified in the rate lookup transaction, pass the RATELOOKUPID in the request of an Authorization or Sale transaction.

Additional Parameters For Rate Lookup Transactions

To perform a rate lookup transaction (TRXTYPE=K), pass the following parameters:

• CURRENCY — Payflow supports ISO 4217 3-letter currency codes. Contact the Planet Payment processor for a list of supported currencies.
• AMT

The rate lookup transaction returns the following response parameters, which are specific to rate lookups:

• RATELOOKUPID — This is the same as the PNREF of this transaction. Pass this in the request of a Sale or Authorization transaction in order to charge the buyer in the CURRENCY specified in the request.
  - MCPTRXCONVRATE — This is a decimal amount, such as, 0.0122289.
  - MCPTRXCONVERTEDAMT — This is the amount passed in the request, converted using the specified conversion rate (MCPTRXCONVRATE).
  - MCPCURRENCYCODE — This is the same currency code that you passed in the request.

Example Rate Lookup Transaction

In this example, you perform an MCP rate lookup transaction for $50 US Dollars (USD) that you would like converted to Australian Dollars (AUD). A RATELOOKUPID is returned in the response, which you then pass in an Authorization transaction request to charge your buyer in AUD.

Submit the rate lookup transaction.

Pass TRXTYPE=K for the rate lookup, the amount that you would like converted and the target currency in the transaction request:

TRXTYPE=K&VENDOR=PayflowMerchant&PARTNER=Partner&PWD=Password&
USER=Username&AMT=50.00&CURRENCY=AUD&VERBOSITY=HIGH

Note the value of the PNREF in the response is the same as the value of the RATELOOKUPID:

RESULT=0&PNREF=MEPR9E547033&RESPMSG=Approved&HOSTCODE=00&RESPTEXT=Approved&RATELOOKUPID=MEPR9E547033
&MCPTRXCONVRATE=0.8939746&MCPTRXCONVERTEDAMT=55.93&MCPCURRENCYCODE=AUD&TRANSTIME=2014-02-27 11:34:11

Note: You do not have to store the values of the MCPTRXCONVRATE, MCPTRXCONVERTEDAMT and the MCPCURENCYCODE parameters returned in the response. These parameters are stored by Payflow. You only need to pass the RATELOOKUPID in the Sale or Authorization transaction that uses the conversion rate.

Submit an Authorization transaction and include the RATELOOKUPID in the request.

TRXTYPE=A&VENDOR=PayflowMerchant&PARTNER=Partner&PWD=Password&USER=Username&TENDER=C
&ACCT=4051700000003926&EXPDATE=1215&AMT=50.00&VERBOSITY=HIGH&RATELOOKUPID=MEPR9E547033

The following is the response:

RESULT=0&PNREF=LWTW9E549039&RESPMSG=Approved&HOSTCODE=00&RESPTEXT=Approved&AMT=50.00
&ACCT=3926&EXPDATE=1215&CARDTYPE=0&MCPTRXCONVRATE=0.8939746&MCPTRXCONVERTEDAMT=55.93
&MCPCURRENCYCODE=AUD&TRANSTIME=2014-02-04 11:34:13

Settle the Authorization transaction as you normally would:

TRXTYPE=D&VENDOR=PayflowMerchant&PARTNER=Partner&PWD=Password
&USER=Username&TENDER=C&AMT=50.00&ORIGID=LWTW9E549039
&VERBOSITY=HIGH

The following is the response:

RESULT=0&PNREF=LWTW9E573609&RESPMSG=Approved&HOSTCODE=00
&RESPTEXT=Approved&TRANSTIME=2014-02-04 11:34:15

Using Address Verification Service

To qualify for the lowest bank rate, pass address verification service information, including the street address and zip (postal) code.

Address verification service compares the submitted billing street address and zip code with the values on file at the cardholder's bank. The response includes values for AVSADDR and AVSZIP: Y, N, or X for the match status of the customer's street address and zip code. Y= match, N = no match, X = cardholder's bank does not support address verification service. The address verification service result is for advice only. Banks do not decline transactions based on the address verification service result. The merchant decides to approve or decline a transaction. Most US banks and some international banks support the address verification service.

Note: Address verification service checks only for a street number match, not a street name match, so 123 Main Street returns the same response as 123 Elm Street.

The international address verification service (IAVS) response indicates whether the address verification service response is international (Y), USA (N), or cannot be determined (X).

Note: When you set VERBOSITY to HIGH, the Gateway returns the raw response from the processor in the PROCAVS field. To obtain details about the meaning of the response, contact your merchant bank.

Example Address Verification Service Parameter String

This example request includes the address verification service parameters BILLTOSTREET and BILLTOZIP:

TRXTYPE=A&TENDER=C&PWD=SuperUserPassword&PARTNER=PayPal&VENDOR=Vendor&USER=SuperMerchant
&ACCT=5555555555554444&EXPDATE=1215&AMT=123.00&BILLTOSTREET=5199 Maple&BILLTOZIP=98765

In this example response, the address value matches the value in the bank's records, but the zip code does not. The AVSZIP response is N.

RESULT=0&PNREF=VXW412345678&RESPMSG=APPROVED&AUTHCODE=123456&AVSADDR=Y&AVSZIP=N&IAVS=X

Using Card Security Code

The card security code is a 3- or 4-digit number (not part of the credit card number) that is printed on the credit card. Because the card security code appears only on the card and not on receipts or statements, the code provides some assurance that the physical card is in the buyer's possession.

This fraud prevention tool has various names, depending on the payment network. Visa calls it CVV2, MasterCard calls it CVC2 while American Express and Discover call it CID. To make sure that your customers see a consistent name, PayPal recommends use of the term card security code on all end-user materials.

On most cards (Diners Club, Discover, Mastercard and Visa) the card security code is a 3-digit number printed on the back of the card (usually in the signature field). All or part of the card number appears before the card security code (567 in the example). American Express prints a 4-digit number (1122 in the example) on the front of the card, above and to the right of the embossed account number. Make sure that you explain this to your customers.

To validate the card security code in a transaction, pass the card security code value in the CVV2 parameter in your request. The response parameter CVV2MATCH returns the result of the card security code check.

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

Card security code

The following is an example request parameter string.

TRXTYPE=S&TENDER=C&USER=SuperUser&PWD=SuperUserPassword&VENDOR=SuperUser&PARTNER=PayPal
&ACCT=5105105105105100&EXPDATE=1215&CVV2=123&AMT=99.00&BILLTOFIRSTNAME=John
&BILLTOLASTNAME=Smith&BILLTOSTREET=123 Main St.&BILLTOCITY=San Jose&BILLTOSTATE=CA&BILLTOZIP=12345

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

Information for the PayPal Acquirer

If PayPal is your acquirer, use the following PayPal specific codes.

For all other acquirers, refer to the Country Codes.

Countries and Regions Supported by PayPal

PayPal uses 2-character alpha ISO-3166-1 codes for specifying countries and regions that are supported in fields and variables.

For a complete list of countries and regions supported by PayPal and their 2-character alpha ISO-3166-1 codes, refer to the PayPal API reference list of Countries and Regions.

PayPal Currency Codes

PayPal uses 3-character ISO-4217 codes for specifying currencies in fields and variables. Please refer to the table of currencies supported by PayPal.

table of contents

American Express MCC Restrictions

American Express restricts transactions for certain Merchant Category Classification (MCC) codes, as shown in the table below. PayPal cannot process any American Express transactions at all for these restricted categories.

Note that MCC codes marked in bold were added in April 2015.

Testing Transactions

Before you activate your website or application for use by buyers, test your integration. A simulated payment network handles transactions, enabling you to verify the configuration and operation of your website or application. No money changes hands.

Setting Up The Payflow Gateway Testing Environment

Before testing transactions be sure you are linked to the test servers.

Direct all transactions to the host URL for testing. See Host URL Addresses. PayPal's simulated network processes transactions directed to the URL.

Testing Guidelines

Follow these guidelines for testing.

• While testing, use only the credit card numbers for testing. Other numbers produce an error.
• Expiration date must be a valid date in the future. Use the format mmyy.
• To view the credit card processor that you have selected for testing, see PayPal Manager.

Processors Other Than PayPal

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

Credit Card Numbers for Testing

For processors other than PayPal, use the following credit card numbers for testing. For PayPal test credit card numbers see PayPal credit card numbers for testing.

Result Values for Testing

Result Values Based On Amount Submitted

You can use the amount of the transaction to generate a particular result value. The following table lists the general guidelines for specifying amounts to submit in requests.

Result Values Based On Amount Submitted and Processor

This table lists the RESULT values that you can generate using the amount of the transaction. To generate a specific value, submit an amount of 1000 plus the RESULT value number (for example, submit an amount of 1013 for a RESULT value of 13).

Result Values Based On Alternate Generation Methods

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

Testing Address Verification Service

The Payflow testing server simulates address verification service by returning a value for AVSADDR based on the first 3 characters of the submitted value for BILLTOSTREET.

The testing server returns a value for AVSZIP based on the submitted BILLTOZIP value as shown in the table.

If BILLTOSTREET starts with 667 or higher or begins with a non-numeric character, then the simulator returns AVSADDR=X, AVSZIP=X.

The following table tests AVSADDR.

The following table tests AVSZIP.

Testing Card Security Code

If you submit a value for the card security code, the cardholder's bank returns a Yes / No / Not Supported (Y / N / X) response on whether the value matches the number on file at the bank. Card security code is described in "Card Security Code Validation".

Note: Some processors will decline (RESULT value 12) a transaction if the card security code does not match without returning a CVV2MATCH value. Test the results and check with your processor to determine whether they support card security code checking.

CVV2 value determine the CVV2MATCH result, as shown here.

Testing CVV2MATCH

Testing the Litle Automatic Account Updater Feature

The Litle Automatic Account Updater feature identifies outdated card information, "repairs" it, and substitutes new card information before submitting the transaction to the network. See the Litle Automatic Account Updater section for more information.

Merchants utilizing this feature should check for the presence of the CCUPDATED=Y response parameter, and if it is returned, should also check for the presence of the ACCT and EXPDATE response parameters to determine what card information has been updated.

Merchants can test their integration for the Litle Automatic Account Updater feature in the Payflow pilot test environment by doing the following.

In the ACCT request parameter, pass one of the following testing card numbers:

Note: Only the last 4-digits of the updated credit card number will be returned.

In the EXPDATE request parameter, pass one of the following expiration dates:

In the AMT request parameter, pass an amount that falls within one of the following ranges to bring about different account updater test cases:

PayPal Processor

For the PayPal processor, use the following guidelines.

Note: See PayPal Credit Card Transaction Request Parameters for the request parameters specific to the PayPal Processor.

PayPal Credit Card Numbers for Testing

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

Result Values Based On Amount

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

Transaction Responses

When a transaction finishes, the Payflow server returns a response string made up of name-value pairs.

The following is an example response string:

RESULT=0&PNREF=EFHP0D426A53&RESPMSG=APPROVED&AUTHCODE=25TEST&AVSADDR=Y&AVSZIP=N&CVV2MATCH=Y

Credit Card Transaction Responses

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

Address Verification Service Responses From PayPal

The following table compares the detailed response the PayPal processor returns for address verification to the normalized response value (Y, N, or X) that AVSADDR and AVSZIP return. To obtain the PayPal processor value, set the VERBOSITY parameter to HIGH. The processor value is returned in the PROCAVS response parameter.

The following is an example Authorization request string that sets VERBOSITY to HIGH. Payflow returns the PROCAVS value in the response.

TRXTYPE=A&BILLTOSTREET=123 Main St&BILLTOZIP=00382&TENDER=C&PARTNER=PayPal
&USER=SuperMerchant&PWD=SuperUserPassword&AMT=1.00&ACCT=4111111111111111
&EXPDATE=1215&INVNUM=PONUM1&VERBOSITY=HIGH

The PROCAVS value is returned in the response.

RESULT=0&PNREF=VFHA0FF94691&RESPMSG=Approved&AUTHCODE=245PNI&AVSADDR=Y&AVSZIP=Y
&HOSTCODE=A&PROCAVS=Y&VISACARDLEVEL=12&TRANSTIME=2011-01-12 13:54:35&AMT=1.00
&ACCT=1111&EXPDATE=1215&CARDTYPE=0&IAVS=N

Card Security Code Results

Normalized Card Security Code Results

The CVV2MATCH parameter returns Y, N, or X.

The following table shows the detailed results that the PayPal processor returns for card security codes. To obtain the PayPal processor value, set the VERBOSITY parameter to HIGH. The processor value is returned in the PROCCVV2 response parameter.

BALAMT Response and Stored Value Cards

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

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

American Express Stored Value Card Example

The following authorization request is for a purchase of 123.00.

TRXTYPE=A&TENDER=C&PWD=x1y2z3&PARTNER=PayPal&VENDOR=SuperMerchant
&USER=SuperMerchant&ACCT=5555555555554444&EXPDATE=1215&AMT=123.00
&BILLTOSTREET=5199 MAPLE&BILLTOZIP=94588

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

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

PNREF

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

Storing the PNREF in your records is helpful, especially if you plan to perform the following Payflow transaction types:

• The PNREF value is passed as the ORIGID value (original transaction ID) in delayed capture transactions (TRXTYPE=D), credits (TRXTYPE=C), inquiries (TRXTYPE=I), and voids (TRXTYPE=V).
• The PNREF value is passed as the ORIGID value (original transaction ID) value in reference transactions for authorizations (TRXTYPE=A) and sales (TRXTYPE=S).

The PNREF value is a 12-character string of printable characters. Printable characters also include symbols other than letters and numbers, such as, the question mark (?). However, a PNREF value typically contains letters and numbers only, for example:

• VADE0B248932
• ACRAF23DB3C4

Note: The format of (or the types of values returned in) the PNREF parameter is subject to change without notification; Payflow will only notify merchants if the length of this parameter changes.

RESULT Values and RESPMSG Text

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

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

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

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

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

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

To obtain the raw response code and message returned by the processor set VERBOSITY to HIGH in your request and capture the response values of the HOSTCODE and RESPTEXT parameters.

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

• When RESULT=0, warning information may be returned that is useful to the request application. See the PayPal API documentation for detailed information on corrective actions.
• When RESULT=104, log in to the PayPal website to determine whether the transaction actually went through. If the transaction does not appear in the History section, retry it.

RESULT Values For Communications Errors

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

A value of -1 or -2 usually indicates a configuration error caused by an incorrect URL or by configuration issues with your firewall. For information on firewall configuration, see Preparing the Payflow Gateway Client Application. A value of -1 or -2 can also be possible if the Gateway servers are unavailable, or you specified an incorrect server or socket pair. A value of -1 can also result when there are internet connectivity errors. Contact Customer Service regarding any other errors.

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

Processor-specific Response Parameters

Some of the response parameters returned in a Payflow transaction are processor-specific and are returned only to merchants using a certain processing platform. For a list of processing platforms supported by Payflow, see Processing Platforms Supporting Card-Present Transactions.

See the following response parameters specific to a particular processing platform:

• Litle Response Parameters
• TSYS Response Parameters

Litle Response Parameters

Merchants using the Litle processing platform may see the following transaction response parameters.

Litle Automatic Account Updater

The Litle Automatic Account Updater feature identifies outdated payment card information, "repairs" it, and substitutes new card information before submitting the transaction to the network. To use this feature, you must sign up directly with Litle.

After signing-up for this feature, Payflow merchants will receive a few extra transaction response parameters only for transactions in which the customer's account information has been updated.

If the customer's card number and/or expiration date are currently different from the information passed in the Payflow transaction request, merchants will receive some or all of the following transaction response parameters.

As a result, merchants utilizing this feature should check for the presence of the CCUPDATED=Y response parameter, and if it is returned should also check for the presence of the ACCT and EXPDATE response parameters to determine what information has been updated.

If you would like to test your integration for this feature, see Testing the Litle Automatic Account Updater Feature.

TSYS Response Parameters

Merchants using the TSYS processing platform for Authorization transactions should pass VERBOSITY=HIGH in the request in order to obtain the following response parameters:

table of contents

Processors Requiring Additional Transaction Parameters

Additional parameters are those required by individual processors beyond the core parameters. Parameters are organized alphabetically by processor.

• American Express Additional Credit Card Parameters
• Cielo Payments - Additional Credit Card Parameters
• Elavon Additional Credit Card Parameters
• First Data Merchant Services Nashville - Additional Credit Card Parameters
• First Data Merchant Services North - Additional Credit Card Parameters
• Heartland - Additional Credit Card Parameters
• Litle Additional Credit Card Parameters
• Paymentech Salem New Hampshire Additional Credit Card Parameters for American Express
• PayPal Credit Card Transaction Request Parameters
• SecureNet Additional Credit Card Parameters for American Express
• Vantiv Additional Credit Card Parameters
• WorldPay Additional Credit Card Parameters

American Express Additional Credit Card Parameters

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

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

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

Retail Transaction Advice Addendum - for SWIPE transactions

Internet Transaction Data

Address Verification Service Parameters

Location Transaction Advice Addendum Parameters

Transaction Advice Detail Parameters

Airline Passenger Data Parameters

American Express Other Parameters

Cielo Payments - Additional Credit Card Parameters

In addition to the core credit card parameters, Cielo Payments (formerly Merchant e-Solutions) accepts the parameters described below.

Elavon Additional Credit Card Parameters

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

Elavon Travel Parameters

Elavon also accepts the travel parameters described below.

First Data Merchant Services Nashville - Additional Credit Card Parameters

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

First Data Merchant Services North - Additional Credit Card Parameters

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

Heartland - Additional Credit Card Parameters

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

Litle Additional Credit Card Parameters

Paymentech Salem - New Hampshire - Additional Credit Card Parameters for American Express

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

Paymentech Salem - Internet Transaction Data Parameters

Paymentech Salem - AVS Parameters

Paymentech Salem - Additional Credit Card Parameters for M Record

PayPal Credit Card Transaction Request Parameters

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

SecureNet Additional Credit Card Parameters for American Express

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

SecureNet Retail Transaction Advice Addendum - for SWIPE transactions

SecureNet Internet Transaction Data

SecureNet AVS Parameters

SecureNet Location Transaction Advice Addendum Parameters

SecureNet Transaction Advice Detail Parameters

SecureNet Airline Passenger Data Parameters

SecureNet Other Parameters

Vantiv Additional Credit Card Parameters

Vantiv Additional Credit Card Parameters

Vantiv Soft Merchant Descriptor Parameters

WorldPay Additional Credit Card Parameters

table of contents

TeleCheck Electronic Check Processing

This appendix describes the host-based capture version of the TeleCheck Non-Face-To-Face Check Acceptance (NFTF) services.

TeleCheck NFTF Overview of Services

NFTF offers merchants the convenience of electronic check deposits. When a NFTF transaction is approved by TeleCheck, the manually entered MICR data from the check is electronically converted to an ACH debit and is processed through the ACH Network. The merchant receives funds within two banking days.

NFTF includes TeleCheck Internet Check Acceptance (ICA), Checks By Phone (CBP), and Prearranged Deposit Services (NFTF PPD). Each of these products requires a separate Merchant ID also known as a Subscriber ID. See below for more details.

• ICA provides merchants with the capability to authorize and electronically settle checks presented by customers over the internet. ICA can be single entry or recurring. This is based on customer's authorization received over the internet.
• CBP authorizes and electronically settles checks presented over the phone through customer interaction with a merchant call center representative. CBP services are single entry only. Partial debits and recurring entries are not allowable per NACHA guidelines.
• NFTF prearranged payment and deposit entry (NFTF PPD) may be used for either recurring or non-recurring debits to a customer's account, when the merchant has provided the customer with a written authorization, which the customer has signed or similarly authenticated. Actual payments are facilitated via the internet or via IVR or over the phone. The application type value must be set to PPD. PPD accounts must establish an end date to clearly define terms between customer and merchant, but do not have time period caps.

TeleCheck NFTF Processing Overview

NFTF requirements, processing considerations, and guidelines for processing check payments are described below.

NFTF Requirements

The following requirements must be followed as standard operating procedures to electronically process a NFTF check payment:

• A TeleCheck Merchant ID is required on all transactions and is unique to each location.
• Dual ID is required for all transactions. For personal checks, it must be MICR data and personal check writer identification such as a driver's license. For company checks, it must be MICR data and Federal Tax ID. In the event that a company does not have a Federal Tax ID, the driver's license can also be used.
• For ICA and NFTF PPD, the merchant must retain the customer's authorization of the transaction for a period of 2 years and, for ICA, prompt the customer to print a copy of this confirmation for their records. The merchant must adhere to all authorization requirements, data elements, legal verbiage, and check return fee requirements.
• For CBP, the merchant must audio record the customer's verbal confirmation of the transaction or provide a written confirmation of the transaction to the customer prior to settlement. In either case, the confirmation must be live; IVR is not acceptable for confirmation. If a merchant chooses audio, the merchant must have the technical capability to retain these recordings for a period of 2 years; else the written confirmation may be substituted and retained for the same time period. The merchant must adhere to all authorization requirements; data elements, legal verbiage, and check return fee requirements.
• Only select US accounts drawn on U.S. banks participating in the ACH Network are eligible for processing via the ACH Network.
• TeleCheck Trace ID (TTID) is required for all supplemental messages, change, void, and adjustment transactions.
• Merchant Trace ID is required for all adjustment transactions. This field allows additional capabilities to be enabled such as Overflow Credits and MIA Duplicate Checking.
• Change and Void transactions are only allowed within the original Sale processing window. For NFTF, cutoff time is 4:00PM CST (recommend working with 3:30PM CST).
• Adjustment transactions are electronically allowed within 90 days after the Sale transaction. After the 90 day period, all adjustments must be manually processed.
• A prompt or process must be in place to identify a check as either personal or company.
• Duplicate Checking - TeleCheck has the ability to detect duplicate sale transactions at the point of sale if sent within a predetermined time limit. Duplicates are identified when a sale inquiry is received with the same amount, MICR number, and check number matching a sale inquiry received within the last 2 minutes. If a duplicate is detected it will return an ineligible response for ACH. The 2nd transaction will also receive an ineligible response for ACH with the same ACH Transaction Status and Response Code as the original sale transaction.
• The appropriate Application Type value must be sent to TeleCheck to indicate the type of NFTF transaction (ICA, CBP, or NFTF PPD).
• In the NFTF technical specification several data element fields and features are described as "optional." While these are technically optional, meaning that the product can be technically implemented with or without them, TeleCheck may require the merchant to code to one or more of these optional items based on the agreed upon contractual terms. The merchant may need to account for and enable additional data element fields and product features in their system(s) and in communications to the TeleCheck Authorization System. Various optional data elements throughout each of the message packets could be affected by this requirement.
• First Data Gateway Partners, External Gateway vendors, First Data Platforms, and the Global Gateway Router (GGR) that route merchant transactions to TeleCheck via this specification must code for all fields, features, and functionality available in this specification. Nothing is optional for these partners. Additionally, these partners are required to maintain their NFTF specification as new revisions and addendums become available.

NFTF Processing Considerations

TeleCheck and the Merchant must determine any of the following additional optional features during contract negotiations.

• MIA Duplicate Checking - TeleCheck has the ability to detect duplicate adjustment transactions in back end processes. Adjustments can be submitted up to 90 days after the original Sale transaction. While multiple adjustment transactions are allowed for a given sale transaction, each adjustment transaction must have a unique merchant trace ID. Duplicates are detected when an adjustment transaction is submitted that has the same merchant trace ID as a previously submitted adjustment transaction. If a duplicate adjustment is detected, and the original adjustment was accepted by TeleCheck, the duplicate will also be accepted. The duplicate transaction will then be filtered out by the TeleCheck back end settlement processes.

NFTF Guidelines

The following guidelines should be followed when adhering to the above NFTF Requirements to electronically process a check payment:

• Fields marked as Required are required to process an electronic transaction.
• Not all fields are required by every merchant.
• Unused fields should be completely omitted from the message.
• Each field is variable in length (justification and fillers are not used).
• The order of tagged fields from the POS and from the TeleCheck host are not significant.
• Fields must not have any hard-coded data values.
• The transaction number increments on every attempt.

Message formats outline fields (tags) that are required, not required, or conditional to the Sale, Status, and Adjustment Inquiry packets.

Message Types:

• Merchant Authorization Message and the TeleCheck Authorization Response Message
• Merchant Delayed Capture Message and the TeleCheck Delayed Capture Response Message

Transaction flow Method Messages sent from the Merchant to TeleCheck are authorization messages. Messages sent from TeleCheck to the Merchant are Response messages.

The sale transaction process is often referred to as a 2-part hand-off. The process begins with the merchant's Authorization message. TeleCheck responds with an Authorization response message indicating whether the transaction is approved and whether the check is eligible for conversion (whether check conversion will be offered). The Merchant then responds with a Delayed Capture message, acknowledging receipt of the TeleCheck sale response, and indicating whether electronic check conversion was accepted. TeleCheck completes the transaction with a Delayed Capture response message confirming receipt of the merchant's status inquiry message.

TeleCheck Parameters

Parameters used for processing electronic checks through TeleCheck are described in this section.

Required TeleCheck Parameters