-
-
Website Payments Pro Developer’s Guide © 2006 PayPal Inc. All rights reserved. PayPal, the PayPal logo, Payflow, and Payflow Pro are registered trademarks 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 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Organisation of This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 How to Contact Customer Service . .
-
Contents Chapter 4 Performing Direct Payment Credit Card Transactions . . . 21 How Direct Payment Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 About Direct Payment Credit Card Processing . . . . . . . . . . . . . . . . . . . . . . . 22 Considerations Regarding Your Website Integration . . . . . . . . . . . . . . . . . . 23 Parameters Used in Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Additional Parameters by Transaction Type . . . . . . . .
-
Contents Chapter 5 Testing Credit Card Transactions . . . . . . . . . . . . . . 43 Testing Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Credit Card Numbers Used for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Testing Result Code Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Chapter 6 PayPal Express Checkout Transaction Processing . . . . . 47 What Is PayPal Express Checkout? . . . . . . . . . . . . . . . . .
-
Contents RESULT Codes and RESPMSG Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 RESULT Values for Transaction Declines or Errors . . . . . . . . . . . . . . . . . . . 74 RESULT Values for Communications Errors . . . . . . . . . . . . . . . . . . . . . . 80 Appendix A Verbosity: Viewing Processor-Specific Transaction Results . . . . . . . . . . . . . . . . . . . . . 83 Supported Verbosity Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-
Preface Website Payments Pro Developer’s Guide describes Website Payments Pro and how to integrate it into your website using the Payflow SDK. The product offers two website payment solutions: PayPal Direct Payment and PayPal Express Checkout. Intended Audience This guide is written for merchants who have signed up through PayPal Manager to use PayPal as their processor and Website Payments Pro as their solution for handling payment transactions on their website.
-
Preface Where to Go for More Information z z z z z Chapter 6, “PayPal Express Checkout Transaction Processing”, explains how PayPal Express Checkout works and describes additional (optional) parameters you can send in PayPal Express Checkout transaction requests. Chapter 7, “PayPal Button Placement and Page Designs”, Chapter 8, “Responses to Transaction Requests”, describes parameters returned in transaction responses.
-
1 Website Payments Pro Overview With Website Payments Pro, you get the payment processing capabilities of a merchant account and gateway – plus much more. It is an all-in-one payment solution that includes: z z Direct Payment. Direct Payment enables you to accept credit card payments directly on your website. PayPal remains invisible, so you control the customer experience. PayPal Express Checkout.
-
1 Website Payments Pro Overview Supported Transactions After selecting products to purchase, your customer chooses whether they want to pay using PayPal or pay using credit cards directly on your website. If your customer pays using credit cards on your website, PayPal processes them in the background. If your customer chooses to use PayPal, your customer is transferred to PayPal to log in and select a postal address and payment method, and is returned to your website to complete their purchase.
-
Website Payments Pro Overview Direct Payment Overview 1 Direct Payment Overview Direct Payment offers you direct credit card payment processing capability through PayPal. For credit card transactions, customers can stay on your website as PayPal processes the payment in the background. For each payment, Direct Payment takes the billing address, transaction amount, credit card information and item information as inputs. Within seconds, PayPal returns a confirmation that the transaction has been processed.
-
1 Website Payments Pro Overview Additional Services Additional Services If you have signed up for the Recurring Billing Service, see the Payflow Pro Recurring Billing Service User’s Guide. It is downloadable from the PayPal Manager Documentation page. Business Rules Website Payments Pro must be integrated on your website in the following ways. You must: z z z Present the PayPal Express Checkout button and associated messaging before requesting postal address, billing address and financial information.
-
2 Installing and Configuring the Payflow SDK The Payflow SDK is available either as a standalone client that you can integrate with your web shop 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 Installing and Configuring the Payflow SDK Preparing the Payflow Client Application Preparing the Payflow Client Application Follow these steps to download and install: Step 1 Download the Payflow SDK From the Download page in PayPal Manager (https://manager.paypal.com), 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).
-
3 Creating a Simple Transaction Request This chapter describes how to create a simple Sale transaction request. The chapter focuses on the common set of parameters required in all transactions and how you set up these parameters using name-value pair strings. Additional parameters are required, depending on the transaction type. You can also provide many optional parameters, depending on the results you want returned.
-
3 Creating a Simple Transaction Request Transaction Request Connection Parameters Table 3.1 describes the connection parameters. Pass them in the format and syntax required by the Payflow SDK and programming language that you are using. See your integration documentation for details. TABLE 3.1 Connection parameters Argument Required Description HOSTADDRESS Yes Payflow host name. For live transactions, use payflowpro.verisign.com For testing purposes use pilot-payflowpro.verisign.
-
Creating a Simple Transaction Request Transaction Request 3 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.
-
3 Creating a Simple Transaction Request Sale Transaction Example TABLE 3.2 Required transaction parameters(Continued) Parameter Description Required Type Max. Length PWD The 6 to 32-character password that you defined while registering for the account. The examples in this document use PWD=SuperUserPassword. This value is case-sensitive. Yes Alphanumeric 32 TENDER The tender type (method of payment).
-
Creating a Simple Transaction Request How to Format a Transaction 3 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.
-
3 20 Creating a Simple Transaction Request How to Format a Transaction Website Payments Pro Developer’s Guide
-
4 Performing Direct Payment Credit Card Transactions This chapter provides guidelines on how to implement PayPal Direct Payment transactions. Direct Payment offers you credit card payment processing capability through PayPal directly from the buyer’s credit card. N O T E : Direct Payment is not a standalone feature. You must use Direct Payment together with PayPal Express Checkout.
-
4 Performing Direct Payment Credit Card Transactions How Direct Payment Works H o w D i r e c t P a y m e n t Wo r k s Figure 3-1 shows the general flow of customer checkout with Direct Payment. The numbered steps in the figure are described below: 1. On your website, the customer chooses to pay with a credit card and enters the credit card number and other details. 2. The customer reviews the order. 3.
-
Performing Direct Payment Credit Card Transactions Parameters Used in Transactions 4 For an Authorisation, PayPal sends the transaction information to the cardholder’s issuing bank. The issuing bank checks whether the card is valid, evaluates whether sufficient credit exists, checks values such as Address Verification Service and card security codes, and returns a response: Approval, Decline, Referral, or others.
-
4 Performing Direct Payment Credit Card Transactions Parameters Used in Transactions N O T E : Unless otherwise noted, the parameters in Table 4.1 can be used in Direct Payment and PayPal Express Checkout transactions. See Chapter 6, “PayPal Express Checkout Transaction Processing,” for additional (optional) PayPal Express Checkout parameters. TABLE 4.1 Transaction parameters Parameter Description Required Type Max. Length ACCT Payer’s credit card or account number.
-
Performing Direct Payment Credit Card Transactions Parameters Used in Transactions TABLE 4.1 4 Transaction parameters (Continued) Parameter Description Required Type Max. Length ZIP Account holder’s five to nine-digit bill-to ZIP code or other country-specific bill-to postcode. Do not use spaces, dashes or non-numeric characters. ZIP is verified by Address Verification System and the International Address Verification System (described on page 39).
-
4 Performing Direct Payment Credit Card Transactions Parameters Used in Transactions TABLE 4.1 Transaction parameters (Continued) Parameter Description Required Type Max. Length 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) No Alpha 3 CUSTOM A free-form field for your own use.
-
Performing Direct Payment Credit Card Transactions 4 Parameters Used in Transactions TABLE 4.1 Transaction parameters (Continued) Parameter Description Required Type Max. Length HANDLINGAMT Total packing costs for this order. No Decimal 10 N O T E : You must set CURRENCY to one of the three-character currency codes for any of the supported PayPal currencies. See the CURRENCY entry in this table for details. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol.
-
4 Performing Direct Payment Credit Card Transactions Parameters Used in Transactions TABLE 4.1 Transaction parameters (Continued) Parameter Description Required Type Max. Length MERCHANTSESSIONID Your customer Direct Payment session identification token. PayPal records this session token as an additional means to detect possible fraud. No String 64 NAME Information (Next two table entries) FIRSTNAME Account holder's first name.
-
Performing Direct Payment Credit Card Transactions Additional Parameters by Transaction Type TABLE 4.1 4 Transaction parameters (Continued) Parameter Description Required Type Max. Length TAXAMT Sum of tax for all items in this order. No Decimal 10 No Alpha N O T E : You must set CURRENCY to one of the three-character currency codes for any of the supported PayPal currencies. See the CURRENCY entry in this table for details. Limitations: Must not exceed $10,000 USD in any currency.
-
4 Performing Direct Payment Credit Card Transactions Submitting Sale Transactions When to Use a Sale Transaction A Sale transaction is best suited to businesses that provide immediate fulfilment for their products or services. Electronic goods merchants, for example, who fulfil orders immediately can use Sale transactions. If your business does not provide immediate fulfilment, then credit card association rules recommend that you use the Authorisation and Delayed Capture model.
-
Performing Direct Payment Credit Card Transactions Submitting Authorisation/Delayed Capture Transactions 4 Submitting Authorisation/Delayed Capture Transactions An Authorisation (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. One or more Delayed Capture (TRXTYPE=D) transactions are performed after an Authorisation to capture the original Authorisation amount.
-
4 Performing Direct Payment Credit Card Transactions Submitting Authorisation/Delayed Capture Transactions Required Delayed Capture Transaction Parameters To perform a Delayed Capture transaction, you are required to pass the following parameter: ORIGID Set ORIGID to the PNREF (Transaction ID in PayPal Manager reports) value returned from the original transaction. (For details on PNREF, see Chapter 8, “Responses to Transaction Requests.
-
Performing Direct Payment Credit Card Transactions Submitting Authorisation/Delayed Capture Transactions 4 EXAMPLE 4.5 Authorisation response (For details on response parameters, see Chapter 8, “Responses to Transaction Requests.”) RESULT=0&PNREF=EFHP0D426838&RESPMSG=Approved&AVSADDR=N&AVSZIP=Y&CVV2MATCH=X &PPREF=68W3371331353001F&CORRELATIONID=2e52df7ddf292 Step 2 Perform a Delayed Capture transaction Set ORIGID to the PNREF value returned in the original Authorisation transaction response string.
-
4 Performing Direct Payment Credit Card Transactions Submitting Authorisation/Delayed Capture Transactions Step 1 Submit the Initial transaction (Authorisation in this example) This example uses an Authorisation transaction for the full amount of a purchase of $100. EXAMPLE 4.8 Authorisation for the full amount of the purchase "TRXTYPE=A&TENDER=C&PWD=SuperUserPassword&PARTNER=PayPalUK&VENDOR=SuperMerc hant&USER=SuperMerchant&ACCT=5555555555554444&EXPDATE=0308&AMT=100.
-
Performing Direct Payment Credit Card Transactions Submitting Credit Transactions 4 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 server to successfully process it. Conversely, if a capture for a previous Authorisation succeeds, subsequent attempts to capture it again will return an error.
-
4 Performing Direct Payment Credit Card Transactions Submitting Void Transactions Submitting Void Transactions The Void transaction (TRXTYPE=V) prevents a transaction from being settled but does not release the Authorisation (hold on funds) on the cardholder’s account. When to Use a Void Transaction Follow these guidelines: z z You can only void Authorisation transactions. You can only use a Void transaction on a transaction that has not yet settled.
-
Performing Direct Payment Credit Card Transactions Recharging to the Same Credit Card (Reference Transactions) 4 Example Void Transaction Parameter String This is an example Void transaction parameter string. EXAMPLE 4.
-
4 Performing Direct Payment Credit Card Transactions Recharging to the Same Credit Card (Reference Transactions) Transaction Types that Can Be Used as the Original Transaction You can reference any of the supported transaction types shown below to supply data for a new Sale or Authorisation transaction: z z Sale Authorisation (To capture the funds for an approved Authorisation transaction, be sure to perform a Delayed Capture transaction — not a Reference transaction.
-
Performing Direct Payment Credit Card Transactions Using Address Verification Service 4 Note the value of the PNREF in the response. EXAMPLE 4.14 Response to the Authorisation RESULT=0&PNREF=EFHP0D426A51&RESPMSG=Approved&AVSADDR=N&AVSZIP=Y&CVV2MATCH=X &PPREF=6FS950632E172331R&CORRELATIONID=3c1a7c1c411a Step 2 Capture the authorised funds for a partial delivery of $66 When you deliver the first $66 worth of product, you use a normal Delayed Capture transaction to collect the $66.
-
4 Performing Direct Payment Credit Card Transactions Card Security Code Validation N O T E : AVS checks only for a street number match, not a street name match, so 123 Main Street returns the same response as 123 Elm Street. The International Address Verification Service response indicates whether the AVS response is international (Y), USA (N), or cannot be determined (X). SDK version 3.06 or later is required.
-
Performing Direct Payment Credit Card Transactions Card Security Code Validation 4 American Express Card Security Code Enhancements In a card-not-present environment, American Express recommends that you include the following information in your authorisation message: z Card member billing name z Postal information (SHIPTO* parameters) such as: – Address – Name – Postage method z Customer information such as: – – – – z Email address IP address Host name Browser type Order information (such as prod
-
4 Performing Direct Payment Credit Card Transactions Card Security Code Validation Example CVV2 Request Parameter String This example request parameter string includes the CVV2 parameter. EXAMPLE 4.19 CVV2 request parameter string "TRXTYPE=A&TENDER=C&PWD=SuperUserPassword&PARTNER=PayPalUK&VENDOR=SuperMerc hant&USER=SuperMerchant&&ACCT=5555555555554444&EXPDATE=0308&AMT=123.00&CVV 2=567" Example CVV2 Response In this example result, the card security code value matches the value in the bank’s records.
-
5 Testing 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 shopfront — no money changes hands. (You must activate your account and configure your application for live transactions before accepting real orders.
-
5 Testing Credit Card Transactions Testing Result Code Responses TABLE 5.1 Test credit card numbers (Continued) MasterCard 5105105105105100 Visa 4111111111111111 Visa 4012888888881881 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. Testing Result Code Responses You can use the amount of the transaction to generate a particular result code. Table 5.
-
Testing Credit Card Transactions Testing Result Code Responses TABLE 5.
-
5 Testing Credit Card Transactions Testing Result Code Responses TABLE 5.
-
6 PayPal Express Checkout Transaction Processing This chapter provides guidelines on how to implement PayPal Express Checkout. The chapter introduces you to this feature and provides the information you need to get started integrating it into your website application. N O T E : If you also plan to use PayPal Direct Payments described in Chapter 4, “Performing Direct Payment Credit Card Transactions,” to process credit cards, you must use PayPal Express Checkout together with Direct Payments.
-
6 PayPal Express Checkout Transaction Processing How PayPal Express Checkout Works How PayPal Express Checkout Works Figure 6.1 summarises the PayPal Express Checkout process. FIGURE 6.1 Customer checkout sequence Figure 6.1 shows a typical set of web pages representing your merchant website. The PayPal logo is used by the customer to choose PayPal as their method of payment.
-
PayPal Express Checkout Transaction Processing Sale and Authorisation Transactions 6 The web page layout may differ somewhat from your own web design, but the points at which the PayPal Express Checkout API calls are made and when the customer is redirected to PayPal and back to your website are important to understand. The events that take place at each numbered step in the figure are described below: 1.
-
6 PayPal Express Checkout Transaction Processing PayPal Express Checkout Sale Transaction Example N O T E : PayPal Express Checkout does not support reference transactions for Sales and Authorisations. TABLE 6.1 Mapping PayPal Express Checkout requests to ACTION values Request TRXTYPE ACTION Set Express Checkout Identifies the transaction. S = Sale A = Authorisation Is S (for Set Express Checkout) Get Express Checkout Details Identifies the transaction.
-
PayPal Express Checkout Transaction Processing PayPal Express Checkout Sale Transaction Example 6 In addition to the parameter values required by all transaction types described in Chapter 3, “Creating a Simple Transaction Request,” and the minimum required parameters for a Sale transaction described in Chapter 4, “Performing Direct Payment Credit Card Transactions,” Set Express Checkout requires that you pass data for the following parameters. ACTION AMT RETURNURL CANCELURL EXAMPLE 6.
-
6 PayPal Express Checkout Transaction Processing PayPal Express Checkout Sale Transaction Example EXAMPLE 6.3Generating a web page with a META REFRESH tag
