PayPal Pro Integration Guide Last updated: July 2012
PayPal Pro Integration Guide Document Number: 10116.en_US-201207 © 2012 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 About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Chapter 5 Integrating Your Website Using API . . . . . . . . . . . . . 39 Button Hosting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Using the Button Manager API with PayPal Pro Checkout . . . . . . . . . . . . . . . . . 40 Using URL Returned in the Response (Recommended) . . . . . . . . . . . . . . . . 40 Using Form POST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Encrypting Buttons Using Public and Private Key . . . . . . .
Contents GetTransactionDetails API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 GetTransactionDetails Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 GetTransactionDetails Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 RefundTransaction API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 RefundTransaction Request RefundTransaction Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 . . . . . .
Contents 6
P Preface About This Guide The PayPal Pro Integration Guide describes how to integrate with PayPal Pro. It includes information about: Features and benefits of PayPal Pro. Seller Protection. Moving from Website Payments Standard to PayPal Pro. Integrating your website with PayPal Pro. Customising your hosted payment page. Testing your integration in the Sandbox environment. Verifying the status and authenticity of the transactions before fulfilling the orders.
P Preface Documentation Feedback Documentation Feedback Help us improve this guide by sending feedback to: documentationfeedback@paypal.
1 Getting Started with PayPal Pro Overview PayPal Pro is a payment platform allowing merchants to receive payments funded by card or PayPal account.This solution is hosted by PayPal. You do not have to capture or store credit card information on your website, thereby helping towards achieving PCI compliance. PayPal Pro is the choice for merchants who prefer a solution where all financial details are handled by PayPal.
Getting Started with PayPal Pro How PayPal Pro Works Supports Major Credit and Debit Cards - Supports Visa, MasterCard, Carta Aura (processed by Cetelem), Postepay (Visa), PayPal prepaid card (MasterCard). How PayPal Pro Works In the figure above, the top flow is for paying using your PayPal account and the bottom flow is for paying with a card. To integrate your website with PayPal Pro: 1. Generate a button in your website checkout flow using HTML or API solution.
Getting Started with PayPal Pro Seller Protection Seller Protection If PayPal is the only payment method on your website, transactions processed through Intégral Evolution are eligible for PayPal’s Seller Protection. It covers payments done through the payment flow of your website for items sold domestically and internationally. These items can be purchased using a credit card or through the PayPal account.
Getting Started with PayPal Pro PayPal Express Checkout Transaction Processing Verifying the status of a transaction programatically. To check the initial status of a transaction, use any of the following API operations: – – – – DoExpressCheckoutPayment DoReferenceTransaction DoAuthorization DoReauthorization You can check the subsequent status of a transaction programatically by calling the GetTransactionDetails API operation. For more information, refer to “GetTransactionDetails API” on page 63.
Getting Started with PayPal Pro Introduction to Integrating with PayPal Pro placed on both the product page as well as the shopping cart page and is a great tool to increase checkout conversion. The following steps describe how PayPal Express Checkout works 1. After selecting products to purchase on your website, buyers click Pay with PayPal button. 2. They are redirected to the PayPal site where they log in using their PayPal login and password. 3.
Getting Started with PayPal Pro Introduction to Integrating with PayPal Pro 14
2 Integrating Your Website Using HTML This chapter provides instructions for a simple integration that enables you to begin processing transactions using PayPal Pro. N OTE : PayPal recommends that you implement the simple integration to familiarise yourself with PayPal Pro before implementing a more customised integration. As part of a simple integration, you get the default settings on your payment page.
Integrating Your Website Using HTML Simple PayPal Pro Integration The return URL is appended with a Transaction ID on the query string during the redirect back from the payment page to your website. This Transaction ID can be used to retrieve the status and verify the authenticity of the transaction. For detailed information on verifying the authenticity of the transaction before fulfilling the order, refer to Chapter 7, “Order Processing.
Integrating Your Website Using HTML HTML Variables HTML Variables The table below lists the PayPal Pro HTML variables you can use to send in additional transaction information along with your web request. For a list of HTML variables that you can use to customise the look and feel of your payment page, refer to Table 3.1, “HTML Variables for Look and Feel of Payment Page. N OTE : The values you pass must not contain any of these special characters (){}<>\"; N OTE : Some merchants are required to pass bi
Integrating Your Website Using HTML HTML Variables TABLE 2.1 HTML Variables for Settings of Payment Page (Continued) Variable Description Required cancel_return The browser will be redirected to this URL if the buyer clicks “Return to Merchant” link. Be sure to enter the complete URL, including http:// or https://. No cbt Sets the text for the “Return to Merchant” link on the PayPal confirmation page.
Integrating Your Website Using HTML HTML Variables TABLE 2.1 HTML Variables for Settings of Payment Page (Continued) Variable Description Required return The URL to which the buyer’s browser is redirected to after completing the payment. Be sure to enter the complete URL, including http:// or https://. No shipping Shipping charged. This amount is added to subtotal for the total amount. No state State of the shipping address. No subtotal Amount charged for the transaction.
Integrating Your Website Using HTML HTML Variables 20
3 Customising Your PayPal Payment Page You can customise the look and feel of the PayPal payment page in the following two ways: Modifying Your PayPal Account Settings Adding HTML Variables N OTE : HTML variables will override the settings you save on your profile page. Modifying Your PayPal Account Settings In your Profile section on PayPal.com, you can change the look and feel of the payment page by modifying the settings on the following pages under the Website Payment Settings section.
Customising Your PayPal Payment Page Modifying Your PayPal Account Settings 22
Customising Your PayPal Payment Page Modifying Your PayPal Account Settings Settings This page allows you to select the information you want to collect and display on your payment page and where you want to display the payment confirmation. Although we offer many options on this page, we recommend that you display as few options as possible on the payment page.
Customising Your PayPal Payment Page Modifying Your PayPal Account Settings What information do you want to show on your PayPal Pro payment page? You can select the fields that are displayed on your hosted payment page. You have the following options: Card Information - Buyer's credit card information. This field is always displayed and selected by default.
Customising Your PayPal Payment Page Modifying Your PayPal Account Settings Customisation
Customising Your PayPal Payment Page Modifying Your PayPal Account Settings This page allows you to customise your payment page. You can customise the header, background, title, button, and the order summary column of your payment page. PayPal offers three design templates for you to choose. Template A is the default template, however, you can choose from any of the templates offered. N OTE : Your buyers will not see the payment page until you have completed the HTML integration with your website.
Customising Your PayPal Payment Page Modifying Your PayPal Account Settings Choosing a Template Choose from the following three design templates: Template A Template B Template C Template A. Selected by default - you can customise the header. FIGURE 3.
Customising Your PayPal Payment Page Modifying Your PayPal Account Settings Template B. Customise the header, background, title, button, and the order summary column. FIGURE 3.
Customising Your PayPal Payment Page Modifying Your PayPal Account Settings Template C. Customise the header, background, title, and the button. FIGURE 3.
Customising Your PayPal Payment Page Modifying Your PayPal Account Settings Customising Your Template Consider the following when you customise your template: Header (applicable to Template A, B, and C) - By default, the business name from your profile is shown in the header.
Customising Your PayPal Payment Page Adding HTML Variables Adding HTML Variables The table below lists the PayPal Pro HTML variables you can use to customise the look and feel of your payment page. N OTE : The values you pass must not contain any of these special characters (){}<>\"; TABLE 3.1 HTML Variables for Look and Feel of Payment Page Variable Description bodyBgColor Color of the surrounding background of the payment page. bodyBgImg Image of the surrounding background of the payment page.
Customising Your PayPal Payment Page Adding HTML Variables TABLE 3.1 HTML Variables for Look and Feel of Payment Page 32 Variable Description showCustomerName Display customer name (first name and last name). Default Value: true Allowable Value: true or false, where true = show and false = hide. showBillingAddress Display billing address information. Default Value: true Allowable Value: true or false, where true = show and false = hide. showBillingPhone Display billing phone number.
4 Integrating iFrame in Your Website PayPal offers a compact payment form that can be integrated in an iFrame on your website. Since this form is integrated on your website, the buyer never leaves your website, thereby reducing potential drop-offs. You can also maintain your checkout look and feel in the master frame that surrounds the compact payment form. The credit card fields are part of the compact payment form so you do not have to collect this information separately.
Integrating iFrame in Your Website Integrating iFrame Integrating iFrame Choose one of the following methods to integrate the compact payment form in your website: Manual Integration API Integration IMPO RTANT: For optimal performance, PayPal recommends that you load the iFrame asset before other assets such as images and JavaScripts. If there are too many assets running on your payment page when you load iFrame, the request for the iFrame may not be placed or might get delayed.
Integrating iFrame in Your Website Integrating iFrame 3. Ensure that the target name matches the iFrame name, as highlighted in the example below:
