Express Checkout Integration Guide Last updated: October 2009
Express Checkout Integration Guide Document Number: 100010.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.A.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Chapter 1 Introducing Express Checkout . . . . . . . . . . . . . . . 9 The Express Checkout Experience . . . . . . . . . . . .
Contents Dynamic Image Command Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Dynamic Image Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Locale Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Static PayPal Buttons and Images Source Requirements . . . . . . . . . . . . . . . . . . 23 Chapter 3 PayPal Name-Value Pair API Basics . . . . . . . . . . . . . 25 PayPal API Client-Server Architecture . . . . . . . . . . . .
Contents PayPal Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Custom Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Individual Page Style Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Changing the Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Handling Shipping Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Confirmed Address . . . . . .
Contents Chapter 10 Handling Recurring Payments . . . . . . . . . . . . . . . . 89 How Recurring Payments Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Recurring Payments Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Recurring Payments With Express Checkout . . . . . . . . . . . . . . . . . . . . . . . .
Preface This document describes Express Checkout integration. Intended Audience This document is intended for developers and merchants implementing Express Checkout. 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. Revision History Revision history for Express Checkout Integration Guide.
Revision History 8 October 2009 Express Checkout Integration Guide
1 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.
1 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.
Introducing Express Checkout Getting Started 1 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.
1 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.
Introducing Express Checkout Express Checkout Flow 1 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 67.
1 Introducing Express Checkout Express Checkout Building Blocks 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.
Introducing Express Checkout Express Checkout Building Blocks 1 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.
1 Introducing Express Checkout Express Checkout Building Blocks 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. IMPORTANT: To enable PayPal to redirect back to your website, you must have already invoked the SetExpressCheckout API operation, specifying URLs that PayPal uses to redirect back to your site.
2 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.
2 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.
Express Checkout Button and Logo Image Integration Configuring the Dynamic Image 2 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.
2 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.
Express Checkout Button and Logo Image Integration Dynamic Image Command Reference 2 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.
2 Express Checkout Button and Logo Image Integration Dynamic Image Command Reference Country codes, language priorities, and locale values 22 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
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
2 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.
3 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.
3 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.
PayPal Name-Value Pair API Basics PayPal API Client-Server Architecture 3 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.
3 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.
PayPal Name-Value Pair API Basics Obtaining API Credentials 3 3. Click Request API Credentials. 4. Check Request API signature and click Agree and Submit.
3 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.
PayPal Name-Value Pair API Basics Creating an NVP Request 3 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.
3 PayPal Name-Value Pair API Basics Creating an NVP Request To enable PayPal to authenticate your 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.
PayPal Name-Value Pair API Basics Executing NVP API Operations 3 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.
3 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.
4 Implementing the Simplest Express Checkout Integration The simplest Express Checkout integration requires the following PayPal API operations: SetExpressCheckout, DoExpressCheckoutPayment, and optionally, GetExpressCheckoutDetails.
4 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.
Implementing the Simplest Express Checkout Integration Obtaining Express Checkout Transaction Details 4 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.
4 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.
5 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.
5 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.
Testing an Express Checkout Integration 5
5 Testing an Express Checkout Integration http://www.YourReturnURL.com/ ?token=EC-1NK66318YB717835M&PayerID=7AKUSARZ7SAT8 5. Invoke a form on your site that calls the GetExpressCheckoutDetails API operation on the Sandbox:
Testing an Express Checkout Integration 5
5 44 Testing an Express Checkout Integration October 2009 Express Checkout Integration Guide
6 Customizing Express Checkout You can specify options in Express Checkout API requests that change the appearance, behavior, and flow of the checkout process.
6 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.
Customizing Express Checkout PayPal Review Page Order Details 6 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.
6 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.
Customizing Express Checkout PayPal Review Page Order Details 6 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.
6 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.
Customizing Express Checkout PayPal Review Page Order Details 6 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.
6 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.
Customizing Express Checkout PayPal Review Page Order Details 6 – 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.
6 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.
Customizing Express Checkout PayPal Page Style 6 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.
6 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.
Customizing Express Checkout PayPal Page Style 6 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.
6 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.
Customizing Express Checkout Handling Shipping Addresses 6 The following example sets LOCALCODE to ES (Spain). Request Parameters [requiredSecurityParameters] &METHOD=SetExpressCheckout &RETURNURL=https://... &CANCELURL=https://... &AMT=10.
6 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.
Customizing Express Checkout Handling Shipping Addresses 6 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.
6 Customizing Express Checkout Handling Shipping Addresses Request Parameters [requiredSecurityParameters] &METHOD=SetExpressCheckout &RETURNURL=https://... &CANCELURL=https://... &AMT=10.
Customizing Express Checkout Handling Shipping Addresses 6 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.
6 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.
Customizing Express Checkout Automatically Filling Out the PayPal Login Page 6 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.
6 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.
Customizing Express Checkout User Confirms Order on PayPal 6 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.
6 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.
7 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.
7 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.
Implementing the Instant Update API About the Instant Update API 7 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.
7 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.
Implementing the Instant Update API Following Instant Update API Best Practices 7 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.
7 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.
Implementing the Instant Update API Setting Up the Callback 7 – 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.
7 Implementing the Instant Update API Using the Callback PayPal Review page when callback times out Using the Callback 76 October 2009 Express Checkout Integration Guide
Implementing the Instant Update API Using the Callback 7 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.
7 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.
Implementing the Instant Update API Using the Callback 7 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.
7 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.
8 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.
8 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.
Immediate Payment Integrating Immediate Payment into the Express Checkout Flow 8 – 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.
8 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.
9 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.
9 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.
Handling Payment Settlements Order Payment Action z 9 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.
9 88 Handling Payment Settlements Order Payment Action October 2009 Express Checkout Integration Guide
10 Handling Recurring Payments Set up a recurring payment to handle subscription and other payments that occur on a fixed schedule.
10 Handling Recurring Payments Recurring Payments Terms 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.
Handling Recurring Payments Recurring Payments With Express Checkout 10 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.
10 Handling Recurring Payments Recurring Payments With Express Checkout The circled numbers in the diagram correspond to the following steps: 92 October 2009 Express Checkout Integration Guide
Handling Recurring Payments Recurring Payments With Express Checkout 10 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.
10 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.
Handling Recurring Payments Options for Creating a Recurring Payments Profile 10 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.
10 Handling Recurring Payments Options for Creating a Recurring Payments Profile 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.
Handling Recurring Payments Options for Creating a Recurring Payments Profile 10 Required fields for specifying a trial period NVP SOAP TRIALBILLINGPERIOD ScheduleDetails.TrialPeriod.BillingPeriod TRIALBILLINGFREQUENCY ScheduleDetails.TrialPeriod.BillingFrequency TRIALAMT ScheduleDetails.TrialPeriod.Amount TRIALTOTALBILLINGCYCLES ScheduleDetails.TrialPeriod.
10 Handling Recurring Payments Recurring Payments Profile Status 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.
Handling Recurring Payments Modifying a Recurring Payments Profile NOTE: 10 You can also get information about recurring payments profiles from the PayPal website.
10 Handling Recurring Payments Billing the Outstanding Amount of a Profile 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.
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: 10 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.
10 102 Handling Recurring Payments Recurring Payments Notifications October 2009 Express Checkout Integration Guide
11 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 z Handling Payment Review 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.
11 Using Other PayPal API Operations Handling Payment Review REFUNDTYPE=Partial 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.
Using Other PayPal API Operations Handling Payment Review NOTE: 11 You must use version 58.0 to obtain the initial status information provided by DoExpressCheckoutPayment, DoReferenceTransaction, DoAuthorization, or DoReauthorization. To use payment review with the DoExpressCheckoutPayment, DoReferenceTransaction, DoAuthorization, and DoReauthorization PayPal API operations, you must 1.
11 Using Other PayPal API Operations Handling Payment Review IMPORTANT: 106 For best results, call the GetTransactionDetails API operation every six hours; never call it more frequently than once per hour.
12 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.
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.
Integrating giropay with Express Checkout giropay Integration 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.
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.
