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.
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.
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 . . . . . . . . . .
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 . .
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 . . .
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 . . . . . . . . . . . . . . . . .
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).
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/.
1 Introduction 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.
1 Introduction 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.
Introduction About Security 1 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. IMPO RTANT: To enable testing of Payflow Pro, PayPal provides sample transaction scripts that you customize with your Payflow Pro account information and password.
1 12 Introduction About Security Payflow Pro Developer’s Guide
2 Installing and Configuring the 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. IMPO RTANT: Full API documentation is included with each SDK.
2 14 Installing and Configuring the Payflow APIs Preparing the Payflow Client Application Payflow Pro Developer’s Guide
3 Performing Credit Card Transactions This chapter describes performing credit card transactions. Responses to transaction requests are described in Chapter 4, “Responses to Credit Card Transaction Requests.
3 Performing Credit Card Transactions About Credit Card Processing N O T E : 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.
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.
3 Performing Credit Card Transactions 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.
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.
3 Performing Credit Card Transactions 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 Max. Length ACCT Credit card or purchase card number. This value may not contain spaces, non-numeric characters, or dashes. For example, ACCT=5555555555554444 Yes1 Numeric 19 AMT Amount (US Dollars) U.S.
Performing Credit Card Transactions Parameters Used in Credit Card Transactions TABLE 3.2 Credit-card transaction parameters(Continued) Max. Length Parameter Description Required Type 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.
3 Performing Credit Card Transactions Parameters Used in Credit Card Transactions TABLE 3.2 Credit-card transaction parameters(Continued) Max. Length Parameter Description Required Type 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. Yes Alphanumeric 12 PWD The 6- to 32-character password that you defined while registering for the account.
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.
3 Performing Credit Card Transactions Submitting Sale Transactions USER PWD Each transaction type has additional parameter requirements, as listed in the following sections. Transaction responses are described in Chapter 4, “Responses to Credit Card Transaction Requests.” 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.
Performing Credit Card Transactions Submitting Authorisation/Delayed Capture Transactions transaction information. CVV2 is needed for card security code validation.
3 Performing Credit Card Transactions Submitting Authorisation/Delayed Capture Transactions Typical Authorisation Transaction Parameter String A typical parameter string passed in an Authorisation transaction is the same as a Sale transaction string. The only difference is that the TRXTYPE value is A in an Authorisation. "TRXTYPE=A&TENDER=C&USER=SuperUser&PWD=SuperUserPassword&VENDOR=SuperUser &PARTNER=PayPal&ACCT=5105105105105100&EXPDATE=1209&CVV2=123&AMT=99.00& FNAME=Bill&LNAME=Smith&STREET=123 Main St.
Performing Credit Card Transactions Submitting Authorisation/Delayed Capture Transactions The return data for an Authorisation transaction is the same as for a Sale transaction. To capture the authorised funds, perform a Delayed Capture transaction that includes the value returned for PNREF, as described in Step 2 on page 27. EXAMPLE 3.
3 Performing Credit Card Transactions Submitting Voice Authorisation Transactions Delayed Capture Transaction: Error Handling and Retransmittal If an error occurs while processing a Delayed Capture transaction, it is safe to retry the capture with values that allow the PayPal server to successfully process it. Conversely, if a capture for a previous Authorisation succeeds, subsequent attempts to capture it again will return an error.
Performing Credit Card Transactions Submitting Credit Transactions Submitting Credit Transactions The Credit transaction (TRXTYPE=C) refunds the specified amount to the cardholder. Required Credit Transaction Parameters The required parameter data for a Credit transaction depends on the Allow non-referenced credits security setting for your Payflow Pro account. A non-referenced credit is a Credit transaction that does not use the credit card information from an existing transaction.
3 Performing Credit Card Transactions Submitting Void Transactions Fields Copied From the Original Transaction into the Credit Transaction The following fields are copied from the original transaction into the Credit transaction (if they exist in the original transaction). If you provide a new value for any of these parameters when submitting the Credit transaction, then the new value is used. (Exceptions are ACCT, EXPDATE, and SWIPE. These parameters retain their original values).
Performing Credit Card Transactions Submitting Void Transactions z z You can void Delayed Capture, Sale, Credit, Authorisation, and Voice Authorisation 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, you must submit a Credit transaction.
3 Performing Credit Card Transactions Submitting Inquiry Transactions Submitting Inquiry Transactions An Inquiry transaction (TRXTYPE=I) returns the result and status of a transaction. When To Use an Inquiry Transaction You perform an inquiry using a reference to an original transaction—either the PNREF value returned for the original transaction or the CUSTREF value that you specified for the original transaction.
Performing Credit Card Transactions Recharging to the Same Credit Card (Reference Transactions) 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" Required Parameters When Using the CUSTREF To submit an Inquiry transaction when using the PNREF, you must pass the following parameter: CUSTREF
3 Performing Credit Card Transactions Recharging to the Same Credit Card (Reference Transactions) If you attempt to perform a reference transaction in an account for which reference transactions are disallowed, result code 117 is returned. See PayPal Manager online help for instructions on setting reference transactions and other security features. Sale and Authorisation transactions can make use of a reference transaction as a source of transaction data.
Performing Credit Card Transactions Recharging to the Same Credit Card (Reference Transactions) ACCTTYPE STREET MIDDLENAME BILLTOCOUNTRY LASTNAME SWIPE Example Reference Transaction In this example, you authorise an amount of $100 for a shipment and charge $66 for the first partial shipment using a normal Delayed Capture transaction.
3 Performing Credit Card Transactions Submitting Card-Present (SWIPE) Transactions Submitting Card-Present (SWIPE) Transactions Payflow Pro supports card-present transactions (face-to-face purchases). Follow these guidelines to take advantage of the lower card-present transaction rate: z z z z Contact your merchant account provider to ensure that they support card-present transactions. Contact PayPal Customer Service to request having your account set up properly for accepting and passing swipe data.
Performing Credit Card Transactions Card Security Code Validation “TRXTYPE=S&TENDER=C&PARTNER=PayPal&USER=SuperMerchant&PWD=SuperMerchant&SWI PE[40]=;4912000033330026=15121011000012345678?&AMT=21.00” Card Security Code Validation 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.
3 Performing Credit Card Transactions Card Security Code Validation Even though your processor may be certified for card security code, they may not be certified for all card types (for example, Visa CVV2 or MasterCard CVC2). The list will change as PayPal continues to enhance its service offering.
Performing Credit Card Transactions Card Security Code Validation In this example result, the card security code value matches the value in the bank’s records.
3 40 Performing Credit Card Transactions Card Security Code Validation Payflow Pro Developer’s Guide
4 Responses to Credit Card Transaction Requests This chapter describes the contents of a response to a credit card transaction request. When a transaction finishes, PayPal returns a response string made up of name-value pairs. For example, this is a response to a credit card Sale transaction request: RESULT=0&PNREF=VXYZ01234567&RESPMSG=APPROVED&AUTHCODE=123456 &CVV2MATCH=Y Contents of a Response to a Credit Card Transaction Request All transaction responses include values for RESULT, PNREF, RESPMSG.
4 Responses to Credit Card Transaction Requests PNREF Value TABLE 4.1 Transaction response values(Continued) Field Description Type Length AUTHCODE Returned for Sale, Authorisation, and Voice Authorisation transactions. AUTHCODE is the approval code obtained over the telephone from the processing network. AUTHCODE is required when submitting a Force (F) transaction.
Responses to Credit Card Transaction Requests RESULT Codes and RESPMSG Values 4 RESULT Codes and RESPMSG Values RESULT is the first value returned in the response string. The value of the RESULT parameter indicates the overall status of the transaction attempt. z z z A value of 0 (zero) indicates that no errors occurred and the transaction was approved. A value less than zero indicates that a communication error occurred. In this case, no transaction is attempted.
4 Responses to Credit Card Transaction Requests RESULT Codes and RESPMSG Values TABLE 4.2 44 Payflow transaction RESULT values and RESPMSG text (Continued) RESULT RESPMSG and Explanation 6 Invalid or unsupported currency code 7 Field format error. Invalid information entered. See RESPMSG. 8 Not a transaction server 9 Too many parameters or invalid stream 10 Too many line items 11 Client time-out waiting for response 12 Declined.
Responses to Credit Card Transaction Requests RESULT Codes and RESPMSG Values TABLE 4.2 Payflow transaction RESULT values and RESPMSG text (Continued) RESULT RESPMSG and Explanation 33 Error in canceling the recurring profile 34 Error in forcing the recurring profile 35 Error in reactivating the recurring profile 36 OLTP Transaction failed 37 Invalid recurring profile ID 50 Insufficient funds available in account 51 Exceeds per transaction limit 99 General error. See RESPMSG.
4 Responses to Credit Card Transaction Requests RESULT Codes and RESPMSG Values TABLE 4.2 46 Payflow transaction RESULT values and RESPMSG text (Continued) RESULT RESPMSG and Explanation 114 Card Security Code (CSC) Mismatch. An authorisation may still exist on the cardholder’s account. 115 System busy, try again later 116 VPS Internal error. Failed to lock terminal number 117 Failed merchant rule check.
Responses to Credit Card Transaction Requests RESULT Codes and RESPMSG Values TABLE 4.2 Payflow transaction RESULT values and RESPMSG text (Continued) RESULT RESPMSG and Explanation 150 Issuing bank timed out 151 Issuing bank unavailable 200 Reauth error 201 Order error 402 PIM Adapter Unavailable 403 PIM Adapter stream error 404 PIM Adapter Timeout 600 Cybercash Batch Error 601 Cybercash Query Error 1000 Generic host error.
4 Responses to Credit Card Transaction Requests RESULT Codes and RESPMSG Values TABLE 4.
Responses to Credit Card Transaction Requests RESULT Codes and RESPMSG Values 4 Details of the response message may vary slightly from that shown in the table, depending on your SDK integration. TABLE 4.
4 Responses to Credit Card Transaction Requests RESULT Codes and RESPMSG Values TABLE 4.3 50 RESULT values for communications errors(Continued) RESULT Description - 40 Unexpected Request ID found in request.
5 Testing Payflow Pro Credit Card Transactions To test your application, direct all transactions to pilot-payflowpro.verisign.com. Transactions directed to this URL are processed through PayPal’s simulated payment network, enabling you to test the configuration and operation of your application or storefront — no money changes hands. (You must activate your account and configure your application for live transactions before accepting real orders.
5 Testing Payflow Pro Credit Card Transactions Result Code Responses TABLE 5.1 Test credit card numbers Visa 4222222222222 N O T E : Even though this number has a different character count than the other test numbers, it is the correct and functional number. Result Code Responses This section describes the result code responses that you receive. Testing Result Code Responses You can use the amount of the transaction to generate a particular result code. Table 5.
Testing Payflow Pro Credit Card Transactions Result Code Responses 5 Alternative Methods for Generating Specific Result Codes TABLE 5.3 Result codes supporting the amount control Processing Platform Result Codes Available for Testing American Express APAC 0, 12, 13, 104, 1000 Citibank Singapore 0, 4, 5,12,13,23,24,104, 2000 First Data International 0, 3, 4, 5, 12, 13, 23, 24, 26, 30, 50, 99, 100, 102, 104, 1000 Table 5.4 shows another method for obtaining result codes.
5 Testing Payflow Pro Credit Card Transactions Result Code Responses TABLE 5.
6 Activating Your Payflow Pro Account When you are ready to activate your Payflow Pro account to begin submitting live transactions, follow these steps: 1. Log in to PayPal Manager at https://manager.paypal.com. 2. Click the Click Here to Activate button and follow the on-screen instructions. 3. Change the URL within your web or desktop application to point to the live PayPal payment servers. Change pilot-payflowpro.paypal.com to payflowpro.paypal.com.
6 56 Activating Your Payflow Pro Account Payflow Pro Developer’s Guide
A Processor Details Citibank Singapore Contacting Citibank Singapore (CSIN) Citibank N.A.
A Processor Details Citibank Singapore z Kuwaiti Dinar (KWD), ISO code 414 z South Korean Won (KRW), ISO code 410 z Philippines Peso (PHP), ISO code 608 z Canadian Dollar (CAD), ISO code 124 z South African Rand (ZAR), ISO code 710 z China Yuan Renminbi (CNY), ISO code 156 z United Arab Emirates Dirhams (AED), ISO code 784 z Swiss Franc (CHF), ISO code 756 z Swedish Krona (SEK), ISO code 752 z Norweigan Krona (NOK), ISO code 578 z Danish Krona (DKK), ISO code 208 z Icelandic Krona (
Processor Details Citibank Singapore A Settlement Time Citibank Singapore settles at 9:30 PM Singapore Time. This means any transactions before this time are settled that day.
A Processor Details First Data Resources (FDI) F i r s t D a ta R e s o u r c e s ( F D I ) Contacting First Data International First Data Client Services - Merchant Service Team Level 9, 168 Walker Street NORTH SYDNEY NSW 2060 AUSTRALIA Supported Card Types Payflow accounts processing through FDI can accept the following card types: z Visa z MasterCard z JCB z Diner’s Club z American Express Supported Currencies FDI supports transaction processing in the following currencies: 60 z Australia
Processor Details First Data Resources (FDI) z Philippines Peso (PHP), ISO code 608 z Canadian Dollar (CAD), ISO code 124 z South African Rand (ZAR), ISO code 710 z China Yuan Renminbi (CNY), ISO code 156 z United Arab Emirates Dirhams (AED), ISO code 784 z Swiss Franc (CHF), ISO code 756 z Swedish Krona (SEK), ISO code 752 z Norweigan Krona (NOK), ISO code 578 z Danish Krona (DKK), ISO code 208 z Icelandic Krona (ISK), ISO code 352 z Indonesian Rupiah (IDR), ISO code 360 z Fijian Do
A Processor Details First Data Resources (FDI) TABLE A.2 FDI processor setup Field Name Required Merchant Type Y Merchant Name Y Merchant Address Max Length Default Value UI Type Select box 60 Text field 150 Text field Merchant City Y 45 Text field Postal Code Y 10 Text field Merchant Country Y AU Select box Settlement Time FDI settles at 6:00 PM Australian Eastern Time. This means any transactions before this time are settled that day.
B Verbosity: Viewing ProcessorSpecific Transaction Results Transaction results (especially values for declines and error conditions) returned by each PayPal-supported processor vary in detail level and in format. The Payflow Verbosity parameter enables you to control the kind and level of information you want returned. By default, Verbosity is set to LOW. A LOW setting causes PayPal to normalize the transaction result values.
B Verbosity: Viewing Processor-Specific Transaction Results Supported Verbosity Settings TABLE B.1 64 Verbosity settings (Continued) Field Name Type Length Description TRANSSTATE Integer 10 State of the transaction.
Verbosity: Viewing Processor-Specific Transaction Results Changing the Verbosity Setting B Table B.2 shows the increments that are possible on basic TRANSSTATE values. TABLE B.2 TRANSSTATE increments Increment Meaning +100 No client acknowledgment (ACK) is received (=status 0 in V2), for example, 106 is TRANSSTATE 6. Transactions in this range do not settle.
B 66 Verbosity: Viewing Processor-Specific Transaction Results Changing the Verbosity Setting Payflow Pro Developer’s Guide
C Additional Reporting Parameters This appendix lists parameters whose values can appear in PayPal Manager reports. For example, the Shipping and Billing report displays these values. Some of the following parameters may also have other purposes. TABLE C.
C Additional Reporting Parameters TABLE C.
D XMLPay About XMLPay XMLPay specifies an XML syntax for payment requests and associated responses in a payment-processing network. Instead of using name/value pairs, the Payflow SDK allows the use of XML documents based on XMLPay 2.0 schema. The typical user of XMLPay is an internet merchant or merchant aggregator who wants to dispatch credit card or other payment requests to a financial processing network.
D 70 XMLPay Payflow Pro XMLPay Developer’s Guide Payflow Pro Developer’s Guide
Index Index A F ACCT parameter 20 American Express 57 American Express, card security code acceptance 38 AMT parameter 20 APIs documentation 13 downloading 13 application testing 51 AUTHCODE 42 AUTHCODE parameter 20 FIRSTNAME parameter 21 C K card security code acceptance 38 COMMENT1 parameter 20 COMMENT2 parameter 20 Common Gateway Interface 10 communications errors 48 credit card transaction required parameters 23 credit transaction type 29 currency codes 20 CURRENCY parameter 20 CUSTREF parameter
Index payflowpro.paypal.com 9 pilot-payflowpro.paypal.
Index RESPMSG parameter 43 RESULT parameter 43 transactions commercial card 37 creating 23 credit 29 inquiry 32 sale 24 voice authorisation 28 void 30 TRXTYPE parameter 23 U USER parameter 23 V VENDOR parameter 23 VERBOSITY parameter 23 Verbosity settings 63 voice authorisation transaction type 28 void transaction type 30 Z ZIP parameter 23 Payflow Pro Developer’s Guide 73
Index 74 Payflow Pro Developer’s Guide
