PayPal Payflow Pro - 2007 Developer's Guide
Payflow Pro
Developer’s Guide
For Professional Use Only
Currently only available in English.
A usage Professional Uniquement
Disponible en Anglais uniquement pour l’instant.
Last updated: September 2007
Payflow Pro Developer’s Guide
Document Number: 200010.en_US-200709
© 2007 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other
trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
PayPal (Europe) Ltd. is authorised and regulated by the Financial Services Authority in the United Kingdom as an electronic money institution.
PayPal FSA Register Number: 226056.
Notice of non-liability:
PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Organization of This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
How to Contact Customer Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 9
About Payflow Pro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Host Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
How Payflow Pro Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Payflow Pro Advantages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Supported Processing Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Payflow Pro Recurring Billing Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
About Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Chapter 2 Installing and Configuring the Payflow APIs . . . . . . . .13
Preparing the Payflow Client Application . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 3 Performing Credit Card Transactions . . . . . . . . . . . .15
About Credit Card Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Obtaining an Internet Merchant Account . . . . . . . . . . . . . . . . . . . . . . . . 16
Planning Your Payflow Pro Integration . . . . . . . . . . . . . . . . . . . . . . . . . 16
Complying With the E-commerce Indicator (ECI) . . . . . . . . . . . . . . . . . . . . 17
Handling Credit Card Type Information . . . . . . . . . . . . . . . . . . . . . . . . . 17
Contents of a Transaction Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
PARMLIST Syntax Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
How To Format a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Parameters Used in Credit Card Transactions. . . . . . . . . . . . . . . . . . . . . . . . 19
Values Required by All Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Submitting Sale Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
XMLPay Developer’s Guide 3
Contents
When To Use a Sale Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Additional Parameters for Sale Transactions . . . . . . . . . . . . . . . . . . . . . . 24
Typical Sale Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . . 24
Submitting Authorisation/Delayed Capture Transactions . . . . . . . . . . . . . . . . . . 25
When To Use Authorisation/Delayed Capture Transactions . . . . . . . . . . . . . . . 25
Required Authorisation Transaction Parameters . . . . . . . . . . . . . . . . . . . . 25
Typical Authorisation Transaction Parameter String . . . . . . . . . . . . . . . . . . . 26
Required Delayed Capture Transaction Parameters . . . . . . . . . . . . . . . . . . 26
Delayed Capture Transaction: Capturing Transactions for Lower Amounts . . . . . . . 27
Delayed Capture Transaction: Capturing Transactions for Higher Amounts . . . . . . 27
Delayed Capture Transaction: Error Handling and Retransmittal . . . . . . . . . . . . 28
Submitting Voice Authorisation Transactions . . . . . . . . . . . . . . . . . . . . . . . . 28
When to Use a Voice Authorisation Transaction. . . . . . . . . . . . . . . . . . . . . 28
Required Voice Authorisation Transaction Parameters . . . . . . . . . . . . . . . . . 28
Voice Authorisation Parameter String . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Submitting Credit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Required Credit Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . 29
Credit Transaction Parameter Strings . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Submitting Void Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
When To Use a Void Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Required Void Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 31
Example Void Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . 31
Submitting Inquiry Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
When To Use an Inquiry Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Required Parameters When Using the PNREF . . . . . . . . . . . . . . . . . . . . . 32
Inquiry Transaction Parameter String Using the PNREF . . . . . . . . . . . . . . . . 33
Required Parameters When Using the CUSTREF . . . . . . . . . . . . . . . . . . . 33
Inquiry Transaction Parameter String Using the CUSTREF . . . . . . . . . . . . . . . 33
Recharging to the Same Credit Card (Reference Transactions). . . . . . . . . . . . . . . 33
When To Use a Reference Transaction . . . . . . . . . . . . . . . . . . . . . . . . . 33
Transaction Types that Can Be Used as the Original Transaction . . . . . . . . . . . 34
Fields Copied From Reference Transactions . . . . . . . . . . . . . . . . . . . . . . 34
Example Reference Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Submitting Card-Present (SWIPE) Transactions. . . . . . . . . . . . . . . . . . . . . . . 36
Supported Processing Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Card-present Transaction Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Example Card-present Transaction Parameter String . . . . . . . . . . . . . . . . . . 36
4 XMLPay Developer’s Guide
Contents
Card Security Code Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Processing Platforms and Credit Cards Supporting Card Security Code . . . . . . . . 37
Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Example CVV2 Request Parameter String . . . . . . . . . . . . . . . . . . . . . . . 38
Chapter 4 Responses to Credit Card Transaction Requests . . . . . .41
Contents of a Response to a Credit Card Transaction Request . . . . . . . . . . . . . . . 41
PNREF Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
PNREF Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
RESULT Codes and RESPMSG Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
RESULT Values for Transaction Declines or Errors . . . . . . . . . . . . . . . . . . . 43
RESULT Values for Communications Errors . . . . . . . . . . . . . . . . . . . . . . 48
Chapter 5 Testing Payflow Pro Credit Card Transactions . . . . . . .51
Testing Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Credit Card Numbers Used for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Result Code Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Testing Result Code Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Result Codes Returned Based on Transaction Amount . . . . . . . . . . . . . . . . . 52
Alternative Methods for Generating Specific Result Codes . . . . . . . . . . . . . . . 53
Testing Card Security Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Chapter 6 Activating Your Payflow Pro Account . . . . . . . . . . . .55
Appendix A Processor Details . . . . . . . . . . . . . . . . . . . . . .57
Contacting Citibank Singapore (CSIN) . . . . . . . . . . . . . . . . . . . . . . . . . 57
Supported Card Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Supported Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Supported Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Setting Up the Citibank Singapore Processor . . . . . . . . . . . . . . . . . . . . . . 58
Settlement Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Contacting First Data International . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Supported Card Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Supported Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Supported Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Setting Up the FDI Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Settlement Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
XMLPay Developer’s Guide 5
Contents
Appendix B Verbosity: Viewing Processor-Specific
Transaction Results . . . . . . . . . . . . . . . . . . . . . . . . .63
Supported Verbosity Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Changing the Verbosity Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Setting the Default Verbosity Level for All Transactions . . . . . . . . . . . . . . . . . 65
Setting the Verbosity Level on a Per-Transaction Basis. . . . . . . . . . . . . . . . . 65
Appendix C Additional Reporting Parameters . . . . . . . . . . . . . .67
Appendix D XMLPay . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
About XMLPay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Payflow Pro XMLPay Developer’s Guide . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
6 XMLPay Developer’s Guide
Preface
Payflow Pro is a high performance TCP/IP-based Internet payment solution. Payflow Pro is
pre-integrated with leading e-commerce solutions and is also available as a downloadable
software development kit (SDK).
Intended Audience
This guide assumes that its readers:
z Are experienced web or application developers
z Have a background in payments services
Organization of This Document
This document is organized as follows:
z Chapter 1, “Introduction,” describes the Payflow Pro internet payment solution.
z Chapter 2, “Installing and Configuring the Payflow APIs,” shows a typical Payflow
installation procedure for Windows NT and UNIX.
z Chapter 3, “Performing Credit Card Transactions,” discusses credit card transaction syntax
and parameters and describes how to perform transactions.
z Chapter 4, “Responses to Credit Card Transaction Requests,” describes the responses to
credit card transaction requests.
z Chapter 5, “Testing Payflow Pro Credit Card Transactions,” describes how to test your
Payflow Pro integration for credit card transactions.
z Chapter 6, “Activating Your Payflow Pro Account,” specifies the steps you follow when
you are ready to accept live transactions with Payflow.
z Appendix A, “Processors Requiring Additional Transaction Parameters,” lists processors
and their processor-specific parameters.
z Appendix B, “Verbosity: Viewing Processor-Specific Transaction Results,” describes how
you can use the Payflow Verbosity parameter to control the kind and level of information
you want returned in a transaction response.
z Appendix C, “Additional Reporting Parameters,” details the parameters that can be passed
to the server for reporting purposes.
z Appendix D, “XMLPay,” briefly describes XMLPay and tells where you may obtain a
copy of Payflow Pro XMLPay Developer’s Guide.
Payflow Pro Developer’s Guide 7
Preface
Where to Go for More Information
Where to Go for More Information
PayPal Manager online help describes the use of PayPal Manager—the web-based
administration tool that you use to process transactions manually, issue credits, and generate
reports.
For answers to specific questions about Payflow products, search PayPal’s Knowledge Base at
the following URL:
http://knowledge.paypal.com/.
How to Contact Customer Service
For problems with transaction processing or your connection to the server, contact Customer
Service at gateway-ausupport@paypal.com.
Revision History
Revision history for Payflow Pro Developer’s Guide.
TABLE P.1 Revision History
Date Description
September 2007 Adapted for Australia.
8 Payflow Pro Developer’s Guide
Introduction
1
Payflow Pro is a high performance TCP/IP-based internet payment solution. It is preintegrated with leading e-commerce solutions and is also available as a downloadable software
development kit (Payflow SDK).
About Payflow Pro
Payflow Pro resides on your computer system. It available from the PayPal Manager
Downloads page as a .NET or Java library, or you can build your own API by posting directly
to the Payflow servers via HTTPS.
Payflow Pro is multi-threaded and allows multiple concurrent transactions from a single client.
It can be integrated as a web-based or a non-web-based application.
Host Addresses
Unless you are using a V3 software development kit (SDK), use the new HOSTADDRESS
values:
z For live transactions, use payflowpro.verisign.com
z For testing purposes, use pilot-payflowpro.verisign.com
Otherwise (you are using a V3 SDK in the process of being phased out), continue to use the
host addresses below:
z For live transactions, use payflow.verisign.com
z For testing purposes, use test-payflow.verisign.com
How Payflow Pro Works
Payflow Pro uses a client/server architecture to transfer transaction data from you to the
processing networks, and then returns the authorisation results to you. Payflow Pro can
process real-time credit card transactions and other transaction types to most of the financial
processing centres in the United States and Australia.
1. The Payflow client encrypts each transaction request using the latest Secure Sockets Layer
(SSL) encryption and establishes a secure link with the Payflow server over the internet.
2. The Payflow server, a multi-threaded processing environment, receives the request and
transmits it (over a secure private network) to the appropriate financial processing network
for real-time payment authorisation.
Payflow Pro Developer’s Guide 9
Introduction
1
Supported Processing Platforms
3. The response (approved/declined, and so on) is received from the financial network and is
returned in the same session to the Payflow client.
4. The Payflow client completes each transaction session by transparently sending a
transaction receipt to the server before disconnecting the session.
The entire process is a real-time synchronous transaction. Once connected, the transaction is
immediately processed and the answer returned in about three seconds. Processing
transactions through the Payflow service does not affect or define the time periods of
authorisations, nor does it influence the approval or denial of a transaction by the issuer.
When integrating with Payflow Pro, you need only be concerned with passing all the required
data for transaction authorisation.
Payflow Pro Advantages
z Configurable to any e-commerce application. Payflow Pro is ideal for enterprise
merchants who require complete customizability for a controlled buyer experience.
z Downloadable from PayPal Manager Downloads page, the Payflow SDK can be easily
integrated into a customized e-commerce solution in a matter of hours.
z Integration versatility. Payflow Pro can be integrated as an application library or can be
run using CGI scripts.
Supported Processing Platforms
Payflow Pro supports the following processing platforms:
American Express Asia Pacific (APA)
Citibank Singapore (CSIN)
First Data Resources International (FDI)
See Appendix A, “Processor Details,” for more information.
Payflow Pro 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, a monthly fee of $42 for
36 months with an initial fee of $129.
You enroll separately for the Payflow Pro Recurring Billing Service. Using Payflow Pro to
define and manage recurring transactions is described in Payflow Pro – Recurring Billing
Service User’s Guide and in PayPal Manager online help.
10 Payflow Pro Developer’s Guide
About Security
It is your responsibility to protect your passwords and other confidential data and to
implement security safeguards on your website and in your organization, or to ensure that your
hosting company or internal web operations team is implementing them on your behalf.
IMPORTANT: To enable testing of Payflow Pro, PayPal provides sample transaction scripts
Introduction
About Security
that you customize with your Payflow Pro account information and password.
Because the password is initially stored in the text of the program, it is
vulnerable.
Do not use the test scripts in your production environment. To minimize fraud,
machine passwords should always be encrypted. You must write a program
that encrypts and decrypts your Payflow Pro account password.
1
Payflow Pro Developer’s Guide 11
Introduction
1
About Security
12 Payflow Pro Developer’s Guide
Installing and Configuring the
2
Payflow APIs
The Payflow software development kit (SDK) is available either as a standalone client that
you can integrate with your web store using CGI scripts or as a set of APIs for direct
integration with your application.
This chapter provides instructions for downloading the SDK appropriate to your platform.
IMPORTANT: Full API documentation is included with each SDK.
Supported Platforms
Payflow Pro is available on all major web server platforms in a variety of formats to support
your integration requirements. Payflow Pro is available as a .NET or Java library, or you can
build your own API by posting directly to the Payflow servers via HTTPS.
Preparing the Payflow Client Application
Follow these steps to download and install the Payflow application.
Step 1 Download the Payflow SDK
From the Download section of PayPal Manager, download the Payflow SDK appropriate for
your platform.
Step 2 Extract the files to a local directory
Step 3 Configure your firewall
If you have a stateful firewall, enable outbound traffic for SSL (port 443). The firewall keeps
state on the connection, and automatically permits the inbound response from PayPal.
If you do not have a stateful firewall, enable inbound and outbound traffic for SSL (port 443).
Outbound traffic permits the initial request by Payflow Pro, while inbound permits the
response from PayPal.
Step 4 Read the Readme.txt file
The readme.txt file includes integration information and samples that illustrate how to use the
client in your development environment.
Payflow Pro Developer’s Guide 13
Installing and Configuring the Payflow APIs
2
Preparing the Payflow Client Application
14 Payflow Pro Developer’s Guide
Performing Credit Card
3
Transactions
This chapter describes performing credit card transactions.
Responses to transaction requests are described in Chapter 4, “Responses to Credit Card
Transaction Requests.”
In This Chapter
z “About Credit Card Processing” on page 15
z “Contents of a Transaction Request” on page 18
z “How To Format a Transaction” on page 19
z “Parameters Used in Credit Card Transactions” on page 19
z “Values Required by All Transaction Types” on page 23
z “Submitting Sale Transactions” on page 24
z “Submitting Authorisation/Delayed Capture Transactions” on page 25
z “Submitting Credit Transactions” on page 29
z “Submitting Void Transactions” on page 30
z “Submitting Inquiry Transactions” on page 32
z “Recharging to the Same Credit Card (Reference Transactions)” on page 33
z “Submitting Card-Present (SWIPE) Transactions” on page 36
z “Card Security Code Validation” on page 37
About Credit Card Processing
Credit card processing occurs in two steps — a real-time Authorisation and a capture
(settlement) of the funds that were authorised. As discussed below, you perform these two
steps either as a single transaction or as two transactions, depending on your business model.
For an Authorisation, the server sends the transaction information to a credit card processor
who routes the transaction through the financial networks to the cardholder’s issuing bank.
The issuing bank checks whether the card is valid, evaluates whether sufficient credit exists,
checks values such as card security codes (discussed below), and returns a response:
Approval, Decline, Referral, or others.
You receive the response a few seconds after you submit the transaction to the server. If the
Authorisation is approved, the bank temporarily reserves credit for the amount of the
transaction to prepare to capture (fulfill) the transaction. The hold on funds typically lasts for
about a week.
Payflow Pro Developer’s Guide 15
Performing Credit Card Transactions
3
About Credit Card Processing
N OTE: You cannot remove a hold on funds through the processing networks—you must
contact the card issuing bank to lift a hold early.
Capturing a transaction (also known as settling a transaction) actually transfers the funds to
your bank. At least once a day, PayPal gathers all transactions that are flagged to be settled and
sends them in a batch file to the processor. The processor then charges the issuing bank and
transfers the funds to your bank. It typically takes a few days before the money is actually
available in your account, depending on your bank.
Obtaining an Internet Merchant Account
To accept credit cards over the internet, you need a special account called an Internet Merchant
Account. Your account provider or merchant (acquiring) bank works with a PayPal-supported
credit card processor, such as First Data Resources International or American Express Asia
Pacific. To use Payflow Pro to accept live credit cards, you must provide certain details about
your account to PayPal during the “Go Live” part of the enrolment process.
N OTE: An Internet Merchant Account is a different type of merchant account than a merchant
account used for face-to-face (in-person) retail transactions. It has additional risks
associated with card-not-present (e-commerce) transactions. You need to 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.
Planning Your Payflow Pro Integration
In designing your Payflow Pro integration, you should evaluate the following:
z Whether to use a one-step or two-step transaction process. One-step: Submit a Sale
transaction, which performs the Authorisation and (if successful) then flags the transaction
for settlement. Two-step: Perform an Authorisation-only transaction and then later perform
a Delayed Capture transaction. The Delayed Capture transaction can be for the same
amount as the original transaction or for a lower amount. (In the case of a split shipment,
you can perform a Delayed Capture transaction for the initial shipment and a reference
transaction for the final payment. These transaction types, plus the details of performing a
Delayed Capture for an amount higher than the original, are described in “Submitting
Authorisation/Delayed Capture Transactions” on page 25.)
According to card association rules, most physical goods merchants should use a two-step
process, since settlement should occur when the goods are fulfilled or shipped. A two-step
process is also useful if you want to evaluate information in the response, such as whether
the issuer verifies the billing address, and so on. Electronic goods merchants, who fulfill
the order immediately, can use the one-step process. Check with your Internet Merchant
Account provider for suggestions on the best method for you.
z Whether or how to use risk management tools such as card security code.
Card security code refers to a 3- or 4-digit number that appears on the back of most credit
cards. On American Express, the number appears above and to the right of the embossed
card number. Card security code is known by other names, such as CVV2, depending on
16 Payflow Pro Developer’s Guide
Performing Credit Card Transactions
About Credit Card Processing
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. Card security code is described on
page 37.
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.
z Store information in your local database or use PayPal Manager reports to manage the data.
You may want to store shipping information in your system, or you may prefer to send the
information to PayPal with the transaction and report on it later.
N OTE: PayPal recommends that you do not store credit card numbers. If you must store
numbers, encrypt and store them behind properly configured firewalls. You should
also consider whether and how to use the merchant-defined fields COMMENT1
and COMMENT2 to help tie reports to your orders/customers or to report on other
information about the transaction.
z If or how you want to integrate with other systems, such as order fulfillment, customer
service, and so on. You may wish to connect these systems directly to Payflow Pro for
capturing funds, issuing refunds/credits, and so on. Alternatively, you may prefer to
perform these steps manually using PayPal Manager. Either way, PayPal recommends that
you monitor transaction activity using PayPal Manager.
z You may want to discuss, with your Internet Merchant Acquirer, practices that help you to
obtain the most advantageous rates.
Complying With the E-commerce Indicator (ECI)
Some processors support a software flag called E-commerce Indicator (ECI) that indicates that
the associated transaction is an internet transaction. Payflow Pro complies with ECI basic
requirements for all supported processors.
If you use the Buyer Authentication Service, then the ECI values reflects the Authentication
status. See Payflow Pro Fraud Protection Service User’s Guide.
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 that you are not signed up to accept, the Payflow SDK responds with
RESULT code 23, “Invalid account number,” or the processor returns a message that the
customer is not signed up for the card type. For details on RESULT codes and response
messages, see Chapter 4, “Responses to Credit Card Transaction Requests.” 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, you must contact your acquiring bank (the merchant
that holds 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, you must add
Payflow Pro Developer’s Guide 17
Performing Credit Card Transactions
3
Contents of a Transaction Request
the card to your Payflow Pro account through PayPal Manager. See PayPal Manager online
help for details.
Contents of a Transaction Request
Table 3-1 describes the connection parameters that you need to pass when submitting a
transaction request to the Payments gateway. Pass them in the format and syntax required by
the SDK and programming language that you are using. See your integration documentation
for details.
TABLE 3.1 Connection parameters
Argument Required Description
HOSTADDRESS Yes PayPal’s host name.
For live transactions, use payflowpro.verisign.com
For testing purposes, use pilot-payflowpro.verisign.com
HOSTPORT Yes Use port 443
PARMLIST Yes The PARMLIST is the list of parameters that specify the payment
information for the transaction. The quotation marks “ ” at the beginning
and end are required. In the example, the ParmList is:
“TRXTYPE=S&TENDER=C&PARTNER=PayPal&VENDOR=SuperMercha
nt&USER=SuperMerchant&PWD=x1y2z3&ACCT=555555555555444
4&EXPDATE=0308&AMT=123.00”
The content of the PARMLIST varies by the type of transaction being
processed. For example, a Void transaction requires a different set of
parameters than does a Sale transaction.
“Parameters Used in Credit Card Transactions” on page 19 defines the
parameters used to create credit card transactions. “Values Required by
All Transaction Types” on page 23 lists the parameters required by each
transaction type.
TIMEOUT Yes Time-out period for the transaction. The minimum recommended time-
out value is 30 seconds. The PayPal client begins tracking from the time
that it sends the transaction request to the PayPal server.
PROXYADDRESS No Proxy server address. Use the PROXY parameters for servers behind a
firewall. Your network administrator can provide the values.
PROXYPORT No Proxy server port
PROXYLOGON No Proxy server logon ID
PROXYPASSWORD No Proxy server logon password
PARMLIST Syntax Guidelines
Follow these guidelines when creating the PARMLIST:
18 Payflow Pro Developer’s Guide
Performing Credit Card Transactions
How To Format a Transaction
z Spaces are allowed in values.
z Enclose the PARMLIST in quotation marks (“”).
z Quotation marks (“”) are not allowed within the body of the PARMLIST.
z Separate all name-value pairs in the PARMLIST using an ampersand (&).
z Set the VERBOSITY transaction parameter to MEDIUM (default is LOW) if you want the
response to return more detailed information. For details on VERBOSITY, see
Appendix B, “Verbosity: Viewing Processor-Specific Transaction Results
Using Special Characters in Values
Because the ampersand (&) and equal sign (=) characters have special meanings in the
PARMLIST, name-value pairs like the following examples are not valid:
NAME=Ruff & Johnson
COMMENT1=Level=5
To use special characters in the value of a name-value pair, use a length tag. The length tag
specifies the exact number of characters and spaces that appear in the value. The following
name-value pairs are valid:
NAME[14]=Ruff & Johnson
COMMENT1[7]=Level=5
N OTE: Quotation marks (“”) are not allowed even if you use a length tag.
How To Format a Transaction
For details on how to format a transaction based on the above information, refer to the
examples and the supporting documentation provided with your SDK.
Parameters Used in Credit Card Transactions
All credit card processors accept the parameters listed in Tab le 3.2 (required and optional
parameters are noted). “Values Required by All Transaction Types” on page 23 lists the
parameters required for each transaction type.
N OTE: Some processors require yet additional parameters. See the following sections:
z Appendix A, “Processors Requiring Additional Transaction Parameters,” provides
additional parameter requirements for non-PayPal processors.
Payflow Pro Developer’s Guide 19
Performing Credit Card Transactions
3
Parameters Used in Credit Card Transactions
z Appendix C, “Additional Reporting Parameters,” provides a list of parameters that you can
pass for reporting purposes.
TABLE 3.2 Credit-card transaction parameters
Parameter Description Required Type
1
ACCT Credit card or purchase card number.
This value may not contain spaces, non-numeric
characters, or dashes. For example,
ACCT=5555555555554444
AMT Amount (US Dollars) U.S. based currency.
Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma
separators—use 1199.95 not 1,199.95.
Your Internet Merchant Account provider may
stipulate a maximum amount.
Ye s
Ye s
1
Max.
Length
Numeric 19
Numeric 10
AUTHCODE AUTHCODE is returned only for approved Voice
Authorisation transactions. AUTHCODE is the
approval code obtained over the telephone from the
processing network.
COMMENT1 Merchant-defined value for reporting and auditing
purposes.
COMMENT2 Merchant-defined value for reporting and auditing
purposes.
CURRENCY One of the following three-character currency
codes:
z USD (US dollar)
z EUR (Euro)
z GBP (UK pound)
z CAD (Canadian dollar)
z JPY (Japanese Yen)
z AUD (Australian dollar)
NOTE: CURRENCY is applicable only to
processors that support transaction-level
currency. It is not applicable to Australian
Payflow Pro merchants.
req’d for
Voice
Alpha-
numeric
Authorisat
ion only.
No Alpha-
numeric
No Alpha-
numeric
No Alpha 3
6
128
128
20 Payflow Pro Developer’s Guide
Performing Credit Card Transactions
Parameters Used in Credit Card Transactions
ABLE 3.2 Credit-card transaction parameters(Continued)
T
Parameter Description Required Type
Max.
Length
CUSTREF Merchant-defined identifier for reporting and
auditing purposes. For example, you can set
CUSTREF to the invoice number.
You can use CUSTREF when performing Inquiry
transactions. To ensure that you can always access
the correct transaction when performing an Inquiry,
you must provide a unique CUSTREF when
submitting any transaction, including retries.
See STARTTIME and ENDTIME.
CVV2 A 3- or 4-digit code that is printed (not imprinted)
on the back of a credit card. Used as partial
assurance that the card is in the buyer’s possession.
See “Card Security Code Validation” on page 37.
ENDTIME Optional for Inquiry transactions when using
CUSTREF to specify the transaction.
ENDTIME specifies the end of the time period
during which the transaction specified by the
CUSTREF occurred. See STARTTIME.
ENDTIME must be less than 30 days after
STARTTIME. An inquiry cannot be performed
across a date range greater than 30 days.
If you set ENDTIME, and not STARTTIME, then
STARTTIME is defaulted to 30 days before
ENDTIME.
If neither STARTTIME nor ENDTIME is specified,
then the system searches the last 30 days.
Format: yyyymmddhhmmss
EXPDATE Expiration date of the credit card in mmyy format.
For example, 0308 represents March 2008.
No Alpha-
12
numeric
No Alpha-
4
numeric
No Numeric 14
1
Ye s
Numeric 4
NAME or
FIRSTNAME
ORIGID The ID of the original transaction that is being
Account holder's name. This single field holds all of
the person’s name information.
referenced. This ID is returned by the PNREF
No, but
recommended
1
Ye s
Alpha-
numeric
uppercase
Alpha-
numeric
30
12
parameter and appears as the Transaction ID in
PayPal Manager reports.
This value is case-sensitive.
Payflow Pro Developer’s Guide 21
Performing Credit Card Transactions
3
Parameters Used in Credit Card Transactions
T
ABLE 3.2 Credit-card transaction parameters(Continued)
Parameter Description Required Type
Max.
Length
PARTNER The ID provided to you by the authorised PayPal
Reseller who registered you for the Payflow Pro
service. If you purchased your account directly from
PayPal, use VSA.
This value is case-sensitive.
PWD The 6- to 32-character password that you defined
while registering for the account.
This value is case-sensitive.
STARTTIME Optional for Inquiry transactions when using
CUSTREF to specify the transaction.
STARTTIME specifies the beginning of the time
period during which the transaction specified by the
CUSTREF occurred. See ENDTIME.
If you set STARTTIME, and not ENDTIME, then
ENDTIME is defaulted to 30 days after
STARTTIME.
If neither STARTTIME nor ENDTIME is specified,
then the system searches the last 30 days.
Format: yyyymmddhhmmss
STREET The cardholder’s street address (number and street
name).
Ye s A l ph a -
numeric
Ye s A l ph a -
numeric
No Numeric 14
No Alpha-
numeric
12
32
30
SWIPE Used to pass the Track 1 or Track 2 data (the card’s
magnetic stripe information) for card-present
transactions. Include either Track 1 or Track 2
data—not both. If Track 1 is physically damaged,
the POS application can send Track 2 data instead.
NOTE: The track data includes the disallowed =
(equal sign) character. To enable you to use
the data, the SWIPE parameter must include
a length tag specifying the number of
characters in the track data. For this reason,
in addition to passing the track data, the POS
application must count the characters in the
track data and pass that number. Length tags
are described in “Using Special Characters in
Values” on page 19.
TENDER The tender type (method of payment).
C = Credit card
Required
only for
cardpresent
transactions
Ye s A l ph a 1
Alpha-
numeric
22 Payflow Pro Developer’s Guide
Performing Credit Card Transactions
Values Required by All Transaction Types
TABLE 3.2 Credit-card transaction parameters(Continued)
Parameter Description Required Type
Max.
Length
TRXTYPE A single character indicating the type of transaction
to perform. Values are:
S = Sale transaction
C = Credit
A = Authorisation
D = Delayed Capture
V = Void
F = Voice Authorisation
I = Inquiry
USER If you set up one or more additional users on the
account, this value is the ID of the user authorised to
process transactions. If, however, you have not set
up additional users on the account, USER has the
same value as VENDOR.
The examples in this document use
USER=SuperMerchant.
This value is case-sensitive.
VENDOR Your merchant login ID that you created when you
registered for the Payflow Pro account.
The examples in this document use VENDOR =
SuperMerchant.
This value is case sensitive.
Ye s A l ph a 1
Ye s A l ph a -
numeric
Ye s A l ph a -
numeric
64
64
VERBOSITY LOW or MEDIUM.
LOW is the default setting—normalized values.
MEDIUM returns the processor’s raw response
values.
See Appendix B, “Verbosity: Viewing Processor-
Specific Transaction Results.”
ZIP Account holder’s 5- to 9-digit ZIP (postal) code. Do
not use spaces, dashes, or non-numeric characters.
1. Some transaction types do not require this parameter. See “Values Required by All Transaction Types” on page 23
No Alpha
No Alpha 9
Values Required by All Transaction Types
All transaction types require values for the following parameters:
TRXTYPE
TENDER
PART NE R
VENDOR
Payflow Pro Developer’s Guide 23
Loading...