Integration Guide

ManualsBrandsPayPal ManualsSoftwarePayPal Website Payments Pro - 2009

Table Of Contents

Website Payments Pro Integration Guide

Website Payments

Pro Integration Guide

Last updated: October 2009

Summary of content (118 pages)

PAGE 1
Website Payments Pro Integration Guide Last updated: October 2009
PAGE 2
Website Payments Pro Integration Guide Document Number: 100001.en_US-200910 © 2009 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. Copyright © PayPal. All rights reserved. PayPal (Europe) S.à r.l. et Cie., S.C.
PAGE 3
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Chapter 1 Introducing Website Payments Pro . . . . . . . . . . . . . 11 Chapter 2 Introducing Direct Payment . . . . . . . . .
PAGE 4
Contents Set Up the Default Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Set Up Image for Dynamic Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Change the Locale. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Feedback to Buyer Meeting an Incentive . . . . . . . . . . . . . . . . . . . . . . . . 28 Choose the Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Dynamic Image Command Reference . . . . . . .
PAGE 5
Contents PayPal Review Page Order Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Special Instructions to Merchant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Integrating Order Details into the Express Checkout Flow . . . . . . . . . . . . . . . 56 eBay-Issued Incentives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Integrating eBay Incentives into the Express Checkout Flow . . . . . . . . . . . . . . 60 PayPal Page Style . . . . . . . . . . . .
PAGE 6
Contents Sale Payment Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Authorization Payment Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Order Payment Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Chapter 12 Handling Recurring Payments . . . . . . . . . . . . . . . . 97 How Recurring Payments Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Limitations . . . . . . . . . . . . . . . .
PAGE 7
Contents Initiate the Flow with SetExpressCheckout . . . . . . . . . . . . . . . . . . . . . . . 117 Redirect the Customer to PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Complete the Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Receive Transaction Status Notification . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 8
Contents 8 October 2009
PAGE 9
Preface This document describes Website Payments Pro integration. Intended Audience This document is intended for merchants and developers implementing Website Payments Pro. Where to Go for More Information For information on the administrative tasks you can perform from your PayPal account, see the Merchant Setup and Administration Guide. The guide is available on the Documentation page linked to the Library tab in Developer Central.
PAGE 10
Revision History TABLE 1.1 Revision history 10 Date Description 06/30/2008 Complete revision.
PAGE 11
1 Introducing Website Payments Pro PayPal’s Website Payments Pro lets you accept both credit cards and PayPal payments directly on your website. It consists of two API-based solutions: Direct Payment and Express Checkout. Direct Payment lets you accept credit cards on your website. Your customers do not need a PayPal account to pay. Here’s how it works: 1. Your customer pays on your website with their credit card. 2. The payment information is sent to PayPal using the PayPal DoDirectPayment API operation.
PAGE 12
1 12 Introducing Website Payments Pro October 2009 Website Payments Pro Integration Guide
PAGE 13
2 Introducing Direct Payment Direct Payment lets your customers who do not have a PayPal account pay using their credit cards without leaving your website. PayPal then processes the payment in the background. Direct Payment has a single API operation: DoDirectPayment, which allows you to process a credit card transaction. This API operation also alerts you to potentially fraudulent transactions by providing you with industry-standard AVS and CVV2 responses for each transaction.
PAGE 14
2 Introducing Direct Payment Additional Recommendations for Checkout With Direct Payment – Credit card CVV value – Cardholder first and last name – Cardholder billing address NOTE: You must also retrieve the IP address of customer's browser and include this with the request. 2. When your customer clicks the Pay button, invoke the DoDirectPayment API operation. 3. The PayPal API server executes the request and returns a response.
PAGE 15
Introducing Direct Payment Additional Recommendations for Checkout With Direct Payment z 2 Use the optional Invoice ID field to prevent duplicate charges. PayPal ensures that an Invoice ID is used only once per account. Duplicate requests with the same Invoice ID result in an error and a failed transaction.
PAGE 16
2 16 Introducing Direct Payment Additional Recommendations for Checkout With Direct Payment October 2009 Website Payments Pro Integration Guide
PAGE 17
3 Introducing Express Checkout Express Checkout is PayPal’s premier checkout solution, which streamlines the checkout process for buyers and keeps them on the merchant’s site after making a purchase.
PAGE 18
3 Introducing Express Checkout Getting Started process. The buyer can then proceed to review the order on your site. You can include other necessary checkout steps. You can also up-sell to the buyer on your Review Order page. The following diagram shows the Express Checkout flow: Express Checkout Flow In the Express Checkout flow, the buyer 1. Chooses Express Checkout by clicking the Check out with PayPal button 2. Logs into PayPal to authenticate his or her identity 3.
PAGE 19
Introducing Express Checkout Getting Started 3 Configuring and Customizing the Express Checkout Experience After you implement and test your basic Express Checkout integration, you should evaluate the additional features provided by Express Checkout. Express Checkout can be configured and customized to fit into your site. Carefully evaluate each option because the more you do to streamline the checkout process and make Express Checkout seamless to your customers, the more likely your sales will increase.
PAGE 20
3 Introducing Express Checkout Express Checkout Flow Express Checkout Flow You initiate the Express Checkout flow on your shopping cart page and on your payment options page. Express Checkout consists of one flow with two entry points: z At the beginning of the checkout flow; the buyer clicks the Checkout with PayPal button z Upon payment; the buyer selects PayPal as a payment option You must integrate Express Checkout from both entry points. They are explained separately for simplicity.
PAGE 21
Introducing Express Checkout Express Checkout Flow 3 Integrating Express Checkout from the Payment Methodss page Note that if your checkout flow omits the Merchant Review page and proceeds directly to your Confirmation page, you can change the text on the PayPal Review page from Continue to Pay Now. For details on how to change the text on the PayPal Review page from ‘Continue’ to ‘Pay Now’ see “User Confirms Order on PayPal” on page 75.
PAGE 22
3 Introducing Express Checkout Express Checkout Building Blocks To implement the complete Express Checkout flow z On your Shopping Cart page, place the Check out with PayPal button and handle button clicks by setting up the Express Checkout transaction and redirecting your buyer’s browser to PayPal. z On your Payment Methods page, associate the PayPal mark with an option. Handle selection of the PayPal mark by setting up the Express Checkout transaction and redirecting your buyer’s browser to PayPal.
PAGE 23
Introducing Express Checkout Express Checkout Building Blocks 3 Express Checkout Buttons PayPal provides buttons and images for you to place on your website. To implement Express Checkout, you must place the following button on your Shopping Cart page: To implement PayPal as a payment option, which is part of Express Checkout, associate the PayPal mark image with the option.
PAGE 24
3 Introducing Express Checkout Express Checkout Building Blocks Express Checkout Command PayPal provides a command that you use when redirecting to PayPal, which enables your buyer to log into PayPal to approve an Express Checkout payment. When you redirect your buyer’s browser to PayPal, you must specify _ExpressCheckout command for Express Checkout. You also specify the token that identifies the transaction, which was returned by the SetExpressCheckout API operation.
PAGE 25
4 Express Checkout Button and Logo Image Integration PayPal hosts the PayPal button and logo images that you use on your website. Using PayPal’s buttons and logos is convenient and standardizes appearance on websites that use PayPal as a payment option.
PAGE 26
4 Express Checkout Button and Logo Image Integration Dynamic Images z Static image The dynamic images enable PayPal to change their appearance dynamically. If, for example, you have signed up to participate in a PayPal campaign, PayPal can change the appearance of the image dynamically for the duration of that campaign based on parameter information you append to the image URL. By default, the Express Checkout images appears as shown above. The static images cannot be changed dynamically.
PAGE 27
Express Checkout Button and Logo Image Integration Configuring the Dynamic Image 4 Set Up the Default Image The following URL points to the default Check out with PayPal image: https://fpdbs.paypal.com/dynamicimageweb?cmd=_dynamic-image To make the image dynamic, you need only add parameters to this URL to specify the changes you want displayed. To test in the Sandbox environment, send the image to the following Sandbox URL: https://fpdbs.sandbox.paypal.
PAGE 28
4 Express Checkout Button and Logo Image Integration Dynamic Image Command Reference Change the Locale To specify the locale of the image, append the locale parameter set to the code for the appropriate country to the image URL. If a country does not have a localized image or if you do not pass a locale value, the default US image displays. This example displays the image for the Spanish locale: https://fpdbs.paypal.
PAGE 29
Express Checkout Button and Logo Image Integration Dynamic Image Command Reference 4 Dynamic Image Parameters The table below describes the dynamic image name-value pair parameters. Dynamic-Image Command Variable Descriptions Type: encrypted PayPal account number (Optional) Unique identification number. When merchants sign up for a PayPal business account, PayPal assigns them an account number.
PAGE 30
4 Express Checkout Button and Logo Image Integration Dynamic Image Command Reference Country codes, language priorities, and locale values 30 Country code Language priority Locale AT language_0 de_DE AT language_1 en_US AU language_0 en_AU BE language_0 en_US BE language_1 nl_NL BE language_2 fr_FR C2 language_0 en_US C2 language_1 zh_XC C2 language_2 fr_XC C2 language_3 es_XC CH language_0 de_DE CH language_1 fr_FR CH language_2 en_US CN language_0 zh_CN def
PAGE 31
Express Checkout Button and Logo Image Integration Static PayPal Buttons and Images Source Requirements Country code Language priority Locale IE language_0 en_US IT language_0 it_IT IT language_1 en_US JP language_0 ja_JP JP language_1 en_US MQ language_0 fr_FR MQ language_1 en_US NL language_0 nl_NL NL language_1 en_US PL language_0 pl_PL PL language_1 en_US RE language_0 fr_FR RE language_1 en_US US language_0 en_US US language_1 fr_XC US language_2 es_XC
PAGE 32
4 Express Checkout Button and Logo Image Integration Static PayPal Buttons and Images Source Requirements Check out with PayPal button URLs Country Image URL Australia https://www.paypal.com/au/cgibin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside Austria https://www.paypal.com/at/cgibin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside Belgium https://www.paypal.
PAGE 33
5 PayPal Name-Value Pair API Basics The PayPal API uses a client-server model in which your site is a client of the PayPal server. z PayPal API Client-Server Architecture z Obtaining API Credentials z Creating an NVP Request z Executing NVP API Operations z Responding to an NVP Response PayPal API Client-Server Architecture The PayPal API uses a client-server model in which your site is a client of the PayPal server.
PAGE 34
5 PayPal Name-Value Pair API Basics PayPal API Client-Server Architecture The request identifies z The name of the API operation to be performed and its version; for example, SetExpressCheckout for version 52.0 z Credentials that identify the PayPal account making the request z Request-specific information that controls the API operation to be performed A PayPal API server performs the operation and returns a response.
PAGE 35
PayPal Name-Value Pair API Basics PayPal API Client-Server Architecture 5 Token Security Typically, the API operation that sets up a redirection to PayPal returns a token, which is passed as a parameter in the redirect to PayPal. The token also may be required in related API operations.
PAGE 36
5 PayPal Name-Value Pair API Basics Obtaining API Credentials Obtaining API Credentials To use the PayPal API, you must have API credentials that identify you as a PayPal business account holder authorized to perform various API operations. Although you can use either an API signature or a certificate for credentials, PayPal recommends you use a signature. IMPORTANT: You can use either a signature or a certificate; however, you cannot use a signature and a certificate at the same time.
PAGE 37
PayPal Name-Value Pair API Basics Obtaining API Credentials 5 3. Click Request API Credentials. 4. Check Request API signature and click Agree and Submit.
PAGE 38
5 PayPal Name-Value Pair API Basics Creating an NVP Request 5. To complete the process, click Done. Make a note of the API username, API password, and signature. You will need to include this information whenever you execute a PayPal API operation. Creating an API Certificate You must establish credentials to use the PayPal API; however, only create an API certificate if your site requires it—most often, you will want to create an API signature for your credentials.
PAGE 39
PayPal Name-Value Pair API Basics Creating an NVP Request 5 A method specifies the PayPal operation you want to execute. Each method is associated with a version number; together, the method and version defines the exact behavior of the API operation. Typically, the behavior of an API operation does not change between versions; however, you should carefully retest your code whenever you change a version. To specify a method and version number 1. Choose the PayPal API operation you want to use.
PAGE 40
5 PayPal Name-Value Pair API Basics Creating an NVP Request 1. Specify the API user name associated with your account. USER=API_username 2. Specify the password associated with the API user name. PWD=API_password 3. If you are using an API signature and not an API certificate, specify the API signature associated with the API username.
PAGE 41
PayPal Name-Value Pair API Basics Executing NVP API Operations 5 Executing NVP API Operations You execute an PayPal NVP API operation by submitting an HTTP POST request to a PayPal API server. Specifying a PayPal Server You execute a PayPal API operation by submitting the request to a PayPal API server. To execute a PayPal NVP API operation, submit your complete request to one of the following end points: Server end point Description https://api3t.sandbox.paypal.
PAGE 42
5 PayPal Name-Value Pair API Basics Responding to an NVP Response Responding to an NVP Response The Name-Value Pair response consists of the answer to the request as well as common fields that identify the API operation and how it was executed. The following diagram shows fields in the response to a PayPal NVP API operation: Common Response Fields The PayPal API always returns common fields in addition to fields that are specific to the requested PayPal API operation.
PAGE 43
6 Implementing the Simplest Express Checkout Integration The simplest Express Checkout integration requires the following PayPal API operations: SetExpressCheckout, DoExpressCheckoutPayment, and optionally, GetExpressCheckoutDetails.
PAGE 44
6 Implementing the Simplest Express Checkout Integration Setting Up the Express Checkout Transaction NOTE: You can use the return URL to piggyback parameters between pages on your site. For example, you can set your Return URL to specify additional parameters using the https://www.yourcompany.com/page.html?param=value... syntax. The parameters become available as request parameters on the page specified by the Return URL. RETURNURL=return_url 3. Specify the cancel URL.
PAGE 45
Implementing the Simplest Express Checkout Integration Obtaining Express Checkout Transaction Details 6 Obtaining Express Checkout Transaction Details To obtain details about an Express Checkout transaction, you can invoke the GetExpressCheckoutDetails API operation. This example assumes that PayPal redirects to your buyer’s browser with a valid token after the buyer reviews the transaction on PayPal.
PAGE 46
6 Implementing the Simplest Express Checkout Integration Completing the Express Checkout Transaction This example assumes the simplest case, in which the total amount was specified in the return URL when calling the SetExpressCheckout API. Although you can specify additional options, this example does not use any additional options. To execute an Express Checkout transaction 1. Specify the token returned by PayPal when it redirects the buyer’s browser to your site.
PAGE 47
7 Testing an Express Checkout Integration You can test your Express Checkout integration in the Sandbox. This example shows how to simulate your web pages using HTTP forms and supplying the values for API operations from these forms. You can use this strategy for your initial testing; however, for more complete testing, you will want to replace these forms with your web pages containing actual code. The following diagram shows the Express Checkout execution flow, which uses the Sandbox as the API server.
PAGE 48
7 Testing an Express Checkout Integration Express Checkout Execution Flow The following steps match the circled numbers in the diagram. Perform the actions in each step to test Express Checkout. 1. Invoke a form on your site that calls the SetExpressCheckout API on the Sandbox. To invoke the API, set form fields whose names match the NVP names of the fields you want to set, specify their corresponding values, and then post the form to a PayPal Sandbox server, such as https://api-3t.sandbox.paypal.
PAGE 49
Testing an Express Checkout Integration 7
PAGE 50
7 Testing an Express Checkout Integration 5. Invoke a form on your site that calls the GetExpressCheckoutDetails API operation on the Sandbox:
PAGE 51
Testing an Express Checkout Integration 7
PAGE 52
7 52 Testing an Express Checkout Integration October 2009 Website Payments Pro Integration Guide
PAGE 53
8 Customizing Express Checkout You can specify options in Express Checkout API requests that change the appearance, behavior, and flow of the checkout process.
PAGE 54
8 Customizing Express Checkout PayPal Review Page Order Details (9) – Shipping discount. If the buyer is receiving a discount on shipping, the value appears as a credit in this field. (10) – Insurance. If there is insurance on shipping, the insurance fee is shown in this field. (11) – Total. This is the total of the order, including shipping, handling, tax, and other price adjustment-related items.
PAGE 55
Customizing Express Checkout PayPal Review Page Order Details 8 PayPal Review page with order details Special Instructions to Merchant You can allow the buyer to send you special instructions about an order. This feature is especially helpful to buyers who want to customize merchandise. A buyer also might want to tell you to ship their order at a later date because they are out of the country. NOTE: Users of this feature should be sure to read the instructions the buyer sends.
PAGE 56
8 Customizing Express Checkout PayPal Review Page Order Details Continue, the instructions are returned in the responses to GetExpressCheckoutDetails and DoExpressCheckoutPayment. Special Instructions text box Integrating Order Details into the Express Checkout Flow To integrate order details into the checkout flow, pass the Express Checkout parameters described in SetExpressCheckout Order Details Parameters to SetExpressCheckout.
PAGE 57
Customizing Express Checkout PayPal Review Page Order Details 8 SetExpressCheckout Order Details Parameters NVP Field SOAP Field Description and Comments L_NAMEn Name Item name. L_NUMBERn Number Item number. L_DESCn Description Item description. The DESC (NVP) and OrderDescription (SOAP) fields still exist for backwards compatibility.
PAGE 58
8 Customizing Express Checkout PayPal Review Page Order Details Request Parameters: [requiredSecurityParameters] &METHOD=SetExpressCheckout &RETURNURL=http://... &CANCELURL=http://... &PAYMENTACTION=Sale &NAME=J Smith &SHIPTOSTREET=1 Main St &SHIPTOCITY=San Jose &SHIPTOSTATE=CA &SHIPTOCOUNTRYCODE=US &SHIPTOZIP=95131 &L_NAME0=10% Decaf Kona Blend Coffee &L_NUMBER0=623083 &L_DESC0=Size: 8.8-oz &L_AMT0=9.95 &L_QTY0=2 &L_NAME1=Coffee Filter bags &L_NUMBER1=623084 &L_DESC1=Size: Two 24-piece boxes &L_AMT1=39.
PAGE 59
Customizing Express Checkout PayPal Review Page Order Details 8 eBay-Issued Incentives If the buyer’s checkout includes eBay auction items, you must set additional fields in the call to SetExpressCheckout to enable buyers to choose from eBay-issued incentives such as eBay gift certificates, coupons, vouchers, and gift cards that may apply to their order. To enable the display of eBay incentives on the PayPal Review page, you also must provide line item detail information for each eBay item.
PAGE 60
8 Customizing Express Checkout PayPal Review Page Order Details New Total after applying incentives Integrating eBay Incentives into the Express Checkout Flow To integrate eBay incentives into the checkout flow: 1. Pass the following parameters and settings in the call to SetExpressCheckout. – PAYMENTACTION must be Sale – CHANNELTYPE must be eBayItem NOTE: For eBay auctions, you cannot set PAYMENTACTION to Authorization or Order. You must set PAYMENTACTION to Sale. 2.
PAGE 61
Customizing Express Checkout PayPal Review Page Order Details 8 – For multiple eBay items offered as a single order, pass the value returned by eBay when setting up the auction order description in the parameter below: L_EBAYITEMORDERIDn 3. It is recommended that you pass the string “eBay item” in L_DESCn and the eBay Item Number in L_NUMBERn. 4.
PAGE 62
8 Customizing Express Checkout PayPal Page Style Request Parameters: [requiredSecurityParameters] &METHOD=SetExpressCheckout &RETURNURL=http://coffee2go.com &CANCELURL=http://cancel.com &PAYMENTACTION=Sale &EMAIL=jsmith01@example.com &NAME=J Smith &SHIPTOSTREET=1 Main St &SHIPTOCITY=San Jose &SHIPTOSTATE=CA &SHIPTOCOUNTRYCODE=US &SHIPTOZIP=95131 &L_NAME0=Photo &L_NUMBER0=32768923 &L_DESC0=Plastic Frame- An EBay item &L_AMT0=25.
PAGE 63
Customizing Express Checkout PayPal Page Style 8 Custom Page Style When your buyer logs into PayPal to check out, you can make the PayPal pages the buyer sees appear to have a similar look and feel to those on your website. You can customize any of these page characteristics and save the results as a Page Style Name: Up to three unique Page Style Names can be defined in your account.
PAGE 64
8 Customizing Express Checkout PayPal Page Style z Header border color z Header background color z Page background color To define a header image such as your company logo: 1. Create a header image up to 750 pixels wide by 90 pixels high, and save it in a valid graphics format such as .gif, .jpg, or .png. 2. Store the URL to the image on a secure (https) server so your buyer’s web browser does not display a message that the payment contains insecure items. 3.
PAGE 65
Customizing Express Checkout PayPal Page Style 8 Review page with custom header image The following example sets colors for the header background (HDRBACKCOLOR) and header border (HDRBORDERCOLOR). Request Parameters [requiredSecurityParameters] &METHOD=SetExpressCheckout &RETURNURL=https://... &CANCELURL=https://... &AMT=10.
PAGE 66
8 Customizing Express Checkout Changing the Locale Response Parameters [successResponseFields] &TOKEN=EC-17C76533PL706494P The figure below shows the PayPal Login page with HDRBACKCOLOR and HDRBORDERCOLOR set to custom colors. PayPal Login page with custom header background and border colors Changing the Locale You can change the locale of PayPal pages to match the language on your website.
PAGE 67
Customizing Express Checkout Handling Shipping Addresses 8 The following example sets LOCALCODE to ES (Spain). Request Parameters [requiredSecurityParameters] &METHOD=SetExpressCheckout &RETURNURL=https://... &CANCELURL=https://... &AMT=10.
PAGE 68
8 Customizing Express Checkout Handling Shipping Addresses In your SetExpressCheckout request, you can specify the following options: z Require a confirmed address z Not display the shipping address on the review page z Display an alternative address on the review page. Confirmed Address A confirmed address is a shipping address that PayPal has established as belonging to the PayPal account holder.
PAGE 69
Customizing Express Checkout Handling Shipping Addresses 8 Response Parameters [successResponseFields] &TOKEN=EC-6UA07551EA393551U The figure below shows the PayPal review page when REQCONFIRMSHIPPING is set to 1. PayPal review page with a required address Suppressing the Buyer’s Shipping Address You can suppress the display of the buyer’s shipping address on the PayPal pages. You might want to do this in these cases: z You are selling a product or service that does not require shipping.
PAGE 70
8 Customizing Express Checkout Handling Shipping Addresses Request Parameters [requiredSecurityParameters] &METHOD=SetExpressCheckout &RETURNURL=https://... &CANCELURL=https://... &AMT=10.
PAGE 71
Customizing Express Checkout Handling Shipping Addresses 8 PayPal review page with shipping address suppressed Shipping Address Override You can override the buyer’s shipping address stored on PayPal. You would want to do this if, for example, your website registration already requested the customer shipping address. Overriding the shipping address stored on PayPal replaces it with one you specify in the call to SetExpressCheckout. The buyer cannot edit the overridden address.
PAGE 72
8 Customizing Express Checkout Handling Shipping Addresses The following example overrides the shipping address with the address values shown. Request Parameters [requiredSecurityParameters] &METHOD=SetExpressCheckout &RETURNURL=https://... &CANCELURL=https://... AMT=10.
PAGE 73
Customizing Express Checkout Automatically Filling Out the PayPal Login Page 8 PayPal review page with shipping address override Automatically Filling Out the PayPal Login Page When you pass the buyer’s shipping address and contact information (telephone number and email address) parameters in the call to SetExpressCheckout, PayPal automatically fills out the account creation form fields for the buyer on the PayPal Login page.
PAGE 74
8 Customizing Express Checkout Automatically Filling Out the PayPal Login Page Request Parameters [requiredSecurityParameters] &METHOD=SetExpressCheckout &RETURNURL=https://... &CANCELURL=https://... &AMT=10.00 &PAYMENTACTION=Sale &SHIPTOSTREET=1 Main Street &SHIPTOCITY=San Jose &SHIPTOSTATE=CA &SHIPTOCOUNTRYCODE=US &SHIPTOZIP=95131 &EMAIL=jsmith01@example.
PAGE 75
Customizing Express Checkout User Confirms Order on PayPal 8 Pre-populated PayPal Login page User Confirms Order on PayPal If you do not require the buyer to explicitly review and confirm the order on your site, you can configure Express Checkout such that the user commits the payment on PayPal.This reduces a step in the checkout flow. You may want to eliminate your “Review Order” page if there is no additional information you want to collect from the user before they complete the transaction.
PAGE 76
8 Customizing Express Checkout User Confirms Order on PayPal read Pay Now. (After the buyer returns from the PayPal site, you must call DoExpressCheckoutPayment to actually complete the transaction.) To display Pay Now on the button: 1. Get the token from the response to SetExpressCheckout. The response to SetExpressCheckout is the buyer’s token. For example, if the value of RETURNURL passed to SetExpressCheckout is https://www.websitename.
PAGE 77
9 Implementing the Instant Update API The Instant Update API is a callback you can use to obtain the buyer’s shipping address. z About the Instant Update API z How the Callback Works in the Express Checkout Flow z Following Instant Update API Best Practices z Setting Up the Callback z Using the Callback About the Instant Update API The Instant Update API is a server call to your web service that provides an instant update to the PayPal review page.
PAGE 78
9 Implementing the Instant Update API About the Instant Update API 3. Modify the existing Express Checkout API calls to accommodate new parameters. – Send the callback URL, shipping, insurance, and tax information to PayPal in the call to SetExpressCheckout. – Call GetExpressCheckoutDetails to obtain the buyer’s final choices for shipping and insurance, if applicable. – Call DoExpressCheckoutPayment with the buyer’s final selections. 4. Eliminate your shipping options page. 5.
PAGE 79
Implementing the Instant Update API About the Instant Update API 9 PayPal Review page with shipping options, insurance, and tax You can control what options are presented to the buyer as the options can be instantly updated on the page.
PAGE 80
9 Implementing the Instant Update API How the Callback Works in the Express Checkout Flow How the Callback Works in the Express Checkout Flow The figure below shows how the callback integrates into the Express Checkout flow. Callback integrated into Express Checkout flow From left to right, the following events are represented. Text in boldface describes events supporting the callback. 1.
PAGE 81
Implementing the Instant Update API Following Instant Update API Best Practices 9 4. The buyer is redirected to PayPal. 5. When the buyer first logs in to the PayPal site, PayPal obtains the buyer’s shipping address and sends it in the callback request (red down arrow) to your callback server at the specified URL. NOTE: If the buyer changes their shipping address on the PayPal Review page, PayPal will make subsequent calls to the callback request. 6.
PAGE 82
9 Implementing the Instant Update API Setting Up the Callback Setting Up the Callback To set up the callback, you establish a connection with PayPal by providing the location where PayPal can call your web service, along with your shipping options. To start, you must build and operate a secure, reliable, and fast web service that computes the shipping options based on the business rules.
PAGE 83
Implementing the Instant Update API Setting Up the Callback 9 – Option length (L_ITEMLENGTHVALUEn, L_ITEMLENGTHUNITn) – Option width (L_ITEMWIDTHVALUEn, L_ITEMWIDTHUNITn) GetExpressCheckoutDetails and DoExpressCheckoutPayment Changes When you implement the callback, you need to call GetExpressCheckoutDetails and DoExpressCheckoutPayment. GetExpressCheckoutDetails and DoExpressCheckoutPayment include new parameter fields in support of the Instant Update API.
PAGE 84
9 Implementing the Instant Update API Setting Up the Callback PayPal Review page when callback times out 84 October 2009 Website Payments Pro Integration Guide
PAGE 85
Implementing the Instant Update API Using the Callback 9 Using the Callback To use the callback, you add parameter fields to SetExpressCheckout, provide PayPal a URL for sending a callback request, and send PayPal the callback response in Name-Value pair (NVP) format. SetExpressCheckout In the call to SetExpressCheckout, set the following parameters: z Set the CALLBACKURL field to the URL where PayPal can call your web service.
PAGE 86
9 Implementing the Instant Update API Using the Callback [requiredSecurityParameters] &METHOD=SetExpressCheckout &RETURNURL=http://... &CANCELURL=http://... &PAYMENTACTION=Sale &NAME=J Smith &SHIPTOSTREET=1 Main St &SHIPTOCITY=San Jose &SHIPTOSTATE=CA &SHIPTOCOUNTRYCODE=US &SHIPTOZIP=95131 &L_NAME0=10% Decaf Kona Blend Coffee &L_NUMBER0=623083 &L_DESC0=Size: 8.8-oz &L_AMT0=9.95 &L_QTY0=2 &L_NAME1=Coffee Filter bags &L_NUMBER1=6230 &L_DESC1=Size: Two 24-piece boxes &L_AMT1=39.
PAGE 87
Implementing the Instant Update API Using the Callback 9 Callback Request The PayPal sends the parameters in the callback request to the location you specified for CALLBACKURL. The callback request parameters include: z The line-item details you sent in the call to SetExpressCheckout. PayPal also sends back any line-item description details you may have specified such as the L_ITEMWEIGHTUNIT1 and L_ITEMWEIGHTVALUE1 values shown in the example below.
PAGE 88
9 Implementing the Instant Update API Using the Callback METHOD=CallbackResponse &OFFERINSURANCEOPTION=true &L_SHIPPINGOPTIONNAME0=UPS Air &L_SHIPPINGOPTIONLABEL0=UPS Next Day Air Freight &L_SHIPPINGOPTIONAMOUNT0=20.00 &L_TAXAMT0=2.20 &L_INSURANCEAMOUNT0=1.51 &L_SHIPPINGOPTIONISDEFAULT0=false &L_SHIPPINGOPTIONNAME1=UPS Expedited &L_SHIPPINGOPTIONLABEL1=UPS Express 2 Days &L_SHIPPINGOPTIONAMOUNT1=10.00 &L_TAXAMT1=2.00 &L_INSURANCEAMOUNT1=1.
PAGE 89
10 Immediate Payment Immediate Payment ensures buyer payment for an item you are selling on eBay at the time the buyer commits to the item, to avoid unpaid items that drive up the operational cost of your business. You integrate Immediate Payment as additional Express Checkout parameters and use your own off-eBay checkout flow.
PAGE 90
10 Immediate Payment Overview of Immediate Payment From left to right, the following events are represented. The numbered callouts in the figure directly correspond to the numbered comments below: 1. The eBay flow for third-party checkout redirects the buyer from an eBay payment review page to your shopping cart page. On your shopping cart page, the buyer initiates Express Checkout by clicking the Checkout with PayPal button. 2.
PAGE 91
Immediate Payment Integrating Immediate Payment into the Express Checkout Flow 10 – Buyer’s shipping address. 3. The SetExpressCheckout response returns a TOKEN. 4. The buyer is redirected to PayPal. 5. The buyer reviews their payment and clicks Continue. 6. Optionally, you may call GetExpressCheckoutDetails. The GetExpressCheckoutDetails response returns information about the buyer. 7. In the call to DoExpressCheckoutPayment, you must pass the . – ALLOWEDPAYMENTMETHOD: This is the payment method type.
PAGE 92
10 Immediate Payment Integrating Immediate Payment into the Express Checkout Flow cart of eBay and non-eBay items.To allow the buyer to check out just the non-Immediate Payment items, you must provide an appropriate message to the buyer, remove the Immediate Payment item, and retry the transaction. The Call to DoExpressCheckoutPayment To integrate Immediate Payment into the DoExpressCheckoutPayment call: 1. Set ALLOWEDPAYMENTMETHODTYPE to InstantPaymentOnly.
PAGE 93
11 Handling Payment Settlements You can use PayPal API operations to handle the capture of payments authorized using Express Checkout and manage Express Checkout authorization and order payment actions. z Sale Payment Action z Authorization Payment Action z Order Payment Action Sale Payment Action A sale payment action represents a single payment that completes a purchase for a specified amount.
PAGE 94
11 Handling Payment Settlements Order Payment Action An authorization enables you to capture multiple payments up to 115% of, or USD $75 more than, the amount you specify in the DoExpressCheckoutPayment request. Choose this payment action if you need to ship the goods before capturing the payment or if there is some reason not to accept the payment immediately. The honor period, for which funds can be held, is three days. The valid period, for which the authorization is valid, is 29 days.
PAGE 95
Handling Payment Settlements Order Payment Action z 11 Drop shipments, which are shipments from other vendors for which you accept the payment You cannot reauthorize an authorization. You handle the need to reauthorize, for example when the hold period or valid period of an authorization expires, simply by creating another authorization. You can void an order or an authorization created from the order.
PAGE 96
11 96 Handling Payment Settlements Order Payment Action October 2009 Website Payments Pro Integration Guide
PAGE 97
12 Handling Recurring Payments Set up a recurring payment to handle subscription and other payments that occur on a fixed schedule.
PAGE 98
12 Handling Recurring Payments Recurring Payments Terms z Update the details of the recurring payments profile. z Bill the outstanding amount of the recurring payments profile. Limitations The current release of the Recurring Payments API has the following limitations: z A profile can have at most one optional trial period and a single regular payment period. z The profile start date may not be earlier than the profile creation date.
PAGE 99
Handling Recurring Payments Recurring Payments With Express Checkout 12 Recurring payments terms Term Definition Recurring payments profile Your record of a recurring transaction for a single customer. The profile includes all information required to automatically bill the buyer a fixed amount of money at a fixed interval. Billing cycle One payment is made per billing cycle. Each billing cycle is made up of two components.
PAGE 100
12 Handling Recurring Payments Recurring Payments With Express Checkout The circled numbers in the diagram correspond to the following steps: 100 October 2009 Website Payments Pro Integration Guide
PAGE 101
Handling Recurring Payments Recurring Payments With Express Checkout 12 Recurring payments processing flow Step Merchant... PayPal... 1 Calls SetExpressCheckout with one or more billing agreement details in the request 2 3 Returns a token, which identifies the transaction, to the merchant. Redirects buyer’s browser to: https://www.paypal.com/cgibin/webscr?cmd=_express-checkout &token= Displays login page.
PAGE 102
12 Handling Recurring Payments Recurring Payments With Express Checkout z Initiating the processing flow to create one or more billing agreements for recurring payments with no associated one-time purchase or recurring payment NOTE: You can also initiate the processing flow using SetCustomerBillingAgreement for orders that contain only a single recurring payment.
PAGE 103
Handling Recurring Payments Recurring Payments With Direct Payments 12 For redirecting the buyer’s browser to the PayPal login page, PayPal recommends that you use the HTTPS response 302 “Object Moved” with the URL above as the value of the Location header in the HTTPS response. Ensure that you use an SSL-enabled server to prevent browser warnings about a mix of secure and insecure graphics.
PAGE 104
12 Handling Recurring Payments Options for Creating a Recurring Payments Profile Required Fields for CreateRecurringPaymentsProfile With Direct Payments NVP SOAP CREDITCARDTYPE CreditCardDetails.CreditCardType ACCT CreditCardDetails.CreditCardNumber EXPDATE CreditCardDetails.ExpMonth and CreditCardDetails.ExpYear FIRSTNAME CreditCardDetails.CardOwner.PayerName.FirstName LASTNAME CreditCardDetails.CardOwner.PayerName.LastName PROFILESTARTDATE RecurringPaymentProfileDetails.
PAGE 105
Handling Recurring Payments Options for Creating a Recurring Payments Profile 12 Required fields for specifying a regular payment period NVP SOAP Description PROFILESTARTDATE RecurringPaymentsProfileDet ails. BillingStartDate The date when billing for this profile begins. NOTE: The profile may take up to 24 hours for activation. BILLINGPERIOD ScheduleDetails. PaymentPeriod. BillingPeriod The unit of measure for the billing cycle.
PAGE 106
12 Handling Recurring Payments Options for Creating a Recurring Payments Profile Required fields for specifying a trial period NVP SOAP TRIALBILLINGPERIOD ScheduleDetails.TrialPeriod.BillingPeriod TRIALBILLINGFREQUENCY ScheduleDetails.TrialPeriod.BillingFrequency TRIALAMT ScheduleDetails.TrialPeriod.Amount TRIALTOTALBILLINGCYCLES ScheduleDetails.TrialPeriod.
PAGE 107
Handling Recurring Payments Recurring Payments Profile Status 12 Billing the Outstanding Amount If a payment fails due to any reason, the amount that was to be billed (including shipping and tax, if applicable) is added to the profile’s outstanding balance. Use the AUTOBILLOUTAMT field in the CreateRecurringPaymentsProfile request to specify whether or not the outstanding amount should be added to the payment amount for the next billing cycle.
PAGE 108
12 Handling Recurring Payments Modifying a Recurring Payments Profile NOTE: You can also get information about recurring payments profiles from the PayPal website.
PAGE 109
Handling Recurring Payments Billing the Outstanding Amount of a Profile 12 The profile changes take effect with the next payment after the call to update the profile. Say, for example, the buyer has made one trial payment out of a total of three. UpdateRecurringPaymentsProfile is called to increase the number of billing cycles to five. As a result, the buyer will have four additional trial payments to make.
PAGE 110
12 Handling Recurring Payments Recurring Payments Notifications z The profile must have a non-zero outstanding balance. z The amount of the payment cannot exceed the outstanding amount for the profile. z The BillOutstandingAmount call cannot be within 24 hours of a regularly scheduled payment for this profile. NOTE: If another outstanding balance payment is already queued, an API error is returned. You will be informed by IPN about the success or failure of the outstanding payment.
PAGE 111
13 Using Other PayPal API Operations You can use additional PayPal API operations to implement additional features for your buyers or to provide “back office” support. z Issuing Refunds Issuing Refunds You can use the RefundTransaction PayPal API operation to issue refunds. Use the RefundTransaction API to issue one or more refunds associated with a transaction, such as a transaction created by a capture of a payment.
PAGE 112
13 Using Other PayPal API Operations Handling Payment Review 3. For a partial refund, specify the refund amount, including the currency. AMT=amount CURRENCYCODE=currencyID 4. For a partial refund, specify the memo description. NOTE=description 5. Execute the RefundTransaction operation. 6. Check the acknowledgement status in the RefundTransaction response to ensure that the operation was successful.
PAGE 113
Using Other PayPal API Operations Handling Payment Review 13 To use payment review with the DoExpressCheckoutPayment, DoReferenceTransaction, DoAuthorization, and DoReauthorization PayPal API operations, you must 1. Check the payment status in the response to the API operation; specifically, check whether PaymentStatus is set to Pending. 2. If the PaymentStatus is set to Pending, check whether the PendingReason is set to PaymentReview, because there are other reasons that a transaction may become pending.
PAGE 114
13 Using Other PayPal API Operations Handling Payment Review IMPORTANT: 114 For best results, call the GetTransactionDetails API operation every six hours; never call it more frequently than once per hour.
PAGE 115
14 Integrating giropay with Express Checkout You must modify your Express Checkout implementation to use giropay, a common German funding source. z giropay Page Flows z giropay Integration giropay Page Flows If you accept giropay, you must redirect to the giropay website to collect the funds after completing the Express Checkout transaction.
PAGE 116
14 Integrating giropay with Express Checkout giropay Page Flows Page flow for a successful giropay payment Cancelled or Unsuccessful giropay Payment Page Flow If the giropay payment fails for any reason, such as insufficient funds or the customer cancels, PayPal provides details to the customer to do a bank transfer from their bank account. This transaction will remain pending until PayPal receives the funds, at which time the transaction will be complete.
PAGE 117
Integrating giropay with Express Checkout giropay Integration 14 giropay Integration If you offer the giropay payment option, you must take additional steps to integrate with the Express Checkout flow. Initiate the Flow with SetExpressCheckout To support giropay payments, you pass the following three URLs as part of the SetExpressCheckout request. These URLs tell PayPal where to redirect the customer based on the success or failure of each type of payment transaction.
PAGE 118
14 Integrating giropay with Express Checkout giropay Integration Complete the Transaction Corresponding to the three fields passed to SetExpressCheckout, you must add the following three additional pages to your website: Additional pages required for giropay integration NVP Field Description Order Completion The GIROPAYSUCCESSURL page that PayPal redirects the customer to after a successful giropay payment.