PayPal Website Payments Pro - 2011 User Manual

Website Payments Pro Hosted Solution Integration Guide

(Payflow Edition)

Last updated: December 2011

Website Payments Pro Hosted Solution Integration Guide

Document Number: 10112.en_GB-201112

© 2011 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., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L-2449, Luxembourg, R.C.S. Luxembourg B 118 349. Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.

Notice of non-liability: PayPal, Inc. is providing the information i n this document t o you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express, implied or statutory) with respect to the information co ntained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting f rom the application or use of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 1 Getting Started with Website Payments Pro Hosted Solution 7

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Features and Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

How Hosted Solution Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Introduction to Integrating with Hosted Solution . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter 2 Integrating Your Website Using HTML. . . . . . . . . . . .11

Simple Hosted Solution Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Sample Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

HTML Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 3 Customising Your PayPal Payment Page . . . . . . . . . . 17

Modifying Your PayPal Account Settings . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Adding HTML Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Chapter 4 Integrating iFrame in Your Website . . . . . . . . . . . . .29

Integrating iFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

HTML Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

API Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Chapter 5 Integrating Your Website Using API . . . . . . . . . . . . . 35

Button Hosting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Contents

Using the Button Manager API with Hosted Solution Checkout . . . . . . . . . . . . . . . 36

Using URL Returned in the Response (Recommended) . . . . . . . . . . . . . . . . 36

Using Form POST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Encrypting Buttons Using Public and Private Key . . . . . . . . . . . . . . . . . . . . 39

Example of Initiating Hosted Solution Checkout. . . . . . . . . . . . . . . . . . . . . 39

BMCreateButton API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

BMCreateButton Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

BMCreateButton Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

BMCreateButton Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Chapter 6 Order Processing . . . . . . . . . . . . . . . . . . . . . . 45

Verifying Transaction Status and Authenticity . . . . . . . . . . . . . . . . . . . . . . . . 45

Validate Instant Payment Notification (IPN) . . . . . . . . . . . . . . . . . . . . . . . 45

Fulfilling Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Appendix A Obtaining API Credentials. . . . . . . . . . . . . . . . . .47

Creating an API Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Creating an API Certificate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Encrypting Your Certificate Into PKCS12 Format . . . . . . . . . . . . . . . . . . . . . . 48

Importing Your Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Appendix B Error Messages . . . . . . . . . . . . . . . . . . . . . . . 51

Appendix C Currency Codes . . . . . . . . . . . . . . . . . . . . . . .69

Preface

About This Guide

The Website Payments Pro Hosted Solution Integration Guide (Payflow Edition) describes how to integrate with Hosted Solution. It includes information about:

 Features and benefits of Hosted Solution.  Integrating your website with Hosted Solution.  Customising your hosted payment page.  Verifying the status and authenticity of the transactions before fulfilling the orders.

Intended Audience

This guide is for Website Payments Pro Payflow Edition (UK) merchants and developers that want to integrate with Hosted Solution to add transaction processing to their website.

Revision History

The following table lists the history of revisions made to the Website Payments Pro Hosted Solution Integration Guide (Payflow Edition).

TABLE P.1 Revision History for This Guide

Date Published Description

August 2011 Created Website Payments Pro Hosted Solution Integration Guide

Documentation Feedback

Help us improve this guide by sending feedback to:

documentationfeedback@paypal.com

Preface

Documentation Feedback

Overview

Hosted Solution is the fast and easy way to add transaction processing to your website. It is a secure, PayPal-hosted, web-based payment solution that allows you to securely send your buyers to PayPal’s payment page to authorise and process transactions. Buyers pay with a debit or credit card, or their PayPal account and you do not have to capture or store credit card information on your website, thereby helping towards achieving PCI compliance.

Hosted Solution is the choice for merchants who prefer a solution where all financial details are handled by PayPal.

In addition to Hosted Solution, PayPal recommends that you implement the PayPal Express Checkout button on your website. The button appears much earlier in the payment flow and gives existing PayPal account holders the opportunity to use PayPal, thereby increasing the transaction completion rate.

Getting Started with Website Payments Pro Hosted Solution

Features and Benefits

Here are the features and benefits of Hosted Solution:

 PCI compliance - Payment Card Industry (PCI) Data Security Standards (DSS) is a global

security standard which applies to all businesses that collect, store, process, or transmit card holder information. You can use PayPal’s hosted payment page as part of the PCI compliance solution for your business.

NOTE: Hosted Solution implementation helps achieving PCI compliance, and does not

necessarily guarantee it.

 Supports iFrame - PayPal offers a compact payment form that can be integrated in an

iFrame on your website. The buyer completes the payment on your website and you can maintain the checkout look and feel in the master frame that surrounds the compact form.The credit card fields are part of the compact form so you do not have to collect this information separately. For more information, refer to Chapter 4, “Integrating iFrame in

Your Website.

 Support for 3-D Secure Buyer Authentication Protocol - 3-D Secure can help to add an

extra layer of fraud protection for online credit and debit card payments from your buyers. It can benefit your business by helping to reduce the number of unauthorised chargebacks you receive and the time it takes to resolve them. You can enable 3-D Secure via the PayPal-hosted payment page quickly, easily, and at no extra cost.

Getting Started with Website Payments Pro Hosted Solution

How Hosted Solution Works

 Virtual Terminal - PayPal-hosted online payment form, which enables you to accept

phone fax, mail orders for all major credit cards.

 Supports Major Credit and Debit Cards - Supports Visa, Visa Debit, Visa Electron,

MasterCard, and Switch/Maestro.

How Hosted Solution 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.

Getting Started with Website Payments Pro Hosted Solution

Introduction to Integrating with Hosted Solution

To integrate your website with Hosted Solution:

1. Generate a button in your website checkout flow using HTML or API solution. The button could be labeled Pay or Buy or similar. When the buyer clicks this button, they are redirected to the payment page hosted by PayPal.

2. On the payment page, the buyer enters their debit or credit card information and clicks the Pay Now button. The buyer can also elect to use their PayPal account by clicking the Pay with PayPal button.

3. If the transaction is successful, the buyer either sees PayPal’s confirmation page or is

redirected to a URL you specify. If the transaction is unsuccessful, an error message is displayed, and the buyer can rectify the error and retry the transaction.

You can specify the content of the payment page and configure its appearance to reflect the look and feel of your website (including your logo).

Introduction to Integrating with Hosted Solution

After signing up for Hosted Solution, follow these steps to integrate your website with Hosted Solution:

1. Connect your website to Hosted Solution: Identify a point in your website checkout flow where you want to place a Pay or similar button that the buyer clicks on to initiate the payment. You can do this using HTML or API. Clicking on this button redirects the buyer’ s browser to PayPal’s payment page for transaction processing. Depending on how you want to integrate, follow the steps described in Chapter 2, “Integrating Your Website Using

HTML or Chapter 5, “Integrating Your Website Using API.

2. Optionally, customise the appearance and content of your PayPal-hosted payment page by either sending the appropriate HTTP variables or by editing your PayPal account settings. Refer to Chapter 3, “Customising Your PayPal Payment Page.

Getting Started with Website Payments Pro Hosted Solution

Introduction to Integrating with Hosted Solution

Integrating Your Website Using HTML

This chapter provides instructions for a simple integration that enables you to begin processing transactions using Hosted Solution.

NOTE: PayPal recommends that you implement the simple integration to familiarise yourself

with Hosted Solution before implementing a more customised integration.

As part of a simple integration, you get the default settings on your payment page. To customise the look and feel of the page so it matches your website, you can do one of the following:

 Change your settings in your Profile section on PayPal.com, as described in “Modifying

Your PayPal Account Settings” on page 17.

 Add the appropriate HTML variables to the payment page, as described in Table 2.1,

“HTML Variables for Settings of Payment Page and Table 3.1, “HTML Variables for Look and Feel of Payment Page.

IMPORTANT: HTML variables will override the settings you save on your profile page.

Simple Hosted Solution Integration

T o integrate your website with Hosted Solution, identify a point in your website checkout flow where you want to place a button that the buyer clicks to initiate the payment. The button should be labeled Continue to Payment, Pay or similar, and when clicked, should execute a Form POST to PayPal. Clicking on this button redirects the buyer’s browser to the PayPal payment page where they can pay with debit or credit card, or their PayPal account.

The Form POST contains a set of HTML variables that describe the transaction and associate it with your Website Payments Pro account. In the Form POST, you must specify the following:

 subtotal OR total - amount of the transaction  partner - the partner must be PayPalUK.  vendor - Your merchant login ID that you created when you registered for the account.  paymentaction - Indicates whether the transaction is for payment on a final sale or an

authorisation for a final sale (to be captured later).

Integrating Your Website Using HTML

Simple Hosted Solution Integration

The default currency is USD. Additionally, you can specify the appropriate HTML variables listed in Table 2.1, “HTML Variables for Settings of Payment Page to customise the information collected on the payment page or Table 3.1, “HTML Variables for Look and Feel

of Payment Page to customise the look and feel of the page. If the payment is successful, then

the buyer either sees the PayPal confirmation page or is redirected to the URL you specify in your configuration.

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 6, “Order

Processing.

Sample Integration

Below is an example of a simple Hosted Solution integration:

1. Sample Hosted Solution Form POST:

The bold text is the value for the corresponding variable. It is recommended that you enclose the values in quotes. For detailed information on these values, refer to Table 2.1,

“HTML Variables for Settings of Payment Page.

2. Output the HTML text into your website at the point where buyers will proceed with their checkout.

3. Open your checkout page and test the button to ensure that it opens the PayPal payment page.

HTML Variables

The table below lists the Hosted Solution 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.

TABLE 2.1 HTML Variables for Settings of Payment Page

Variable Description Mandatory

Integrating Your Website Using HTML

HTML Variables

address1

address2

address_override

billing_address1

billing_address2

billing_city

billing_country

billing_first_name

billing_last_name

billing_state

billing_zip

Street name of shipping address. (1 of 2 fields) No Street name of shipping address. (2 of 2 fields) No The payer is shown the passed-in address but cannot edit

No it. This variable is overridden if there are errors in the address. The allowable values are true/false. Default is false.

Street name of the billing address. (1 of 2 fields) No Street name of the billing address. (2 of 2 fields) No City name of the billing address. No Country code of the billing address. No First name of person the item is being billed to. No Last name of person the item is being billed to. No State name of the billing address. No Zip code of the billing address. No Identifies the source that built the code for the button.

Format -

buyer_email

cancel_return

cbt

city

country

currency_code

Email address of the buyer. No The browser will be redirected to this URL if the buyer

No clicks “Return to Merchant” link. Be sure to enter the complete URL, including http:// or https://.

Sets the text for the “Return to Merchant” link on the

No PayPal confirmation page. For business accounts, the return button displays your business name in the place of the word “Merchant” by default.

City name of shipping address. No Country name of shipping address. No The currency of the payment. The default is USD. No

Integrating Your Website Using HTML

HTML Variables

ABLE 2.1 HTML Variables for Settings of Payment Page (Continued)

Variable Description Mandatory

custom

discount

first_name

handling

insurance

invoice

last_name

A free-form field for your own use. This variable is never

No presented to the buyer and will be returned in IPN messages.

Shipping discount for this order. Specify the discount as a

No positive amount.

Nine numeric characers plus decimal (.) character. No currency symbol. Specify the exact amount to the cent using a decimal point—use 34.00, not 34. Do not include comma separators—use 1199.95 not 1,199.95.

First name of person the item is being shipped to. No Handling charged. This amount is added to subtotal for

No the total amount.

Total shipping insurance cost for this order. Nine numeric characers plus decimal (.) character. No

currency symbol. Specify the exact amount to the cent using a decimal point—use 34.00, not 34. Do not

include comma separators—use 1199.95 not 1,199.95. Order number in the merchant’s ordering/invoice system. No Last name of person the item is being shipped to. No The language of the login or sign-up page. No

night_phone_a

night_phone_b

night_phone_c

notify_url

partner

The area code of the U.S. phone number, or the country code of the phone number outside the U.S. This prepopulates the buyer’s home phone number.

The three-digit prefix for U.S. phone numbers, or the entire non-U.S. phone number for numbers outside the U.S., excluding the country code. This pre-populates the buyer’s home phone number.

NOTE: Use this variable for non-US numbers.

The four-digit phone number for U.S. phone numbers. This pre-populates the buyer’s home phone number.

The URL to which PayPal posts information about the transaction in the form of Instant Payment Notification. Be sure to enter the complete URL, including http:// or https://.

ID provided to you by the authorized PayPal reseller who registered you for Payflow. If you purchased your account directly from PayPal, use PayPalUK.

Yes

Integrating Your Website Using HTML

HTML Variables

ABLE 2.1 HTML Variables for Settings of Payment Page (Continued)

Variable Description Mandatory

paymentaction

return

shipping

state

subtotal

tax

vendor

Indicates whether the transaction is for payment on a final

Yes sale or an authorisation for a final sale (to be captured later).

 Allowable Values: - authorization or sale  Default Value - sale

The URL to which the buyer’s browser is redirected to

No after completing the payment. Be sure to enter the complete URL, including http:// or https://.

Shipping charged. This amount is added to subtotal for

No the total amount.

State of the shipping address. No Amount charged for the transaction. If shipping, handling,

Yes taxes, insurance, and discount are not specified, this is the total amount charged. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56, not 1,234.56).

You must either pass Taxes charged. This amount is added to subtotal for the

subtotal or total.

No total amount.

Your merchant login ID that you created when you

Yes registered for the account.

total

zip

Total transaction amount, including shipping, handling, taxes, insurance, and discount. The value must include a decimal and the exact amount to the cent (42.00, not 42). Do not include comma separators (1234.56, not 1,234.56).

Postal code of the shipping address. No

Integrating Your Website Using HTML

HTML Variables

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

NOTE: HTML variables will override the settings you save on your profile page.

Modifying Your PayPal Account Settings

In your Service Settings section on PayPal Manager, you can change the look and feel of the payment page by modifying the settings on the following pages under the Hosted Checkout Pages section.

 Configuration  Design

Configuration

This page allows you to select the information you want to collect and display on your payment page, verify enrollment in a buyer authentication program, and decide how you want to display the payment confirmation.

You can make these selections in the following sections:

 Billing and Postal Information  Buyer Authentication Program  Payment Confirmation Page

Customising Your PayPal Payment Page

Modifying Your PayPal Account Settings

Billing and Postal Information

PayPal recommends that you display as few options as possible on the payment page. For example, you may have already collected shipping address on your own website in order to calculate the shipping cost and passed it on to PayPal's payment page. Therefore, it is not necessary to show this option on the payment page again.

You could have information that has already been collected on your website, but you may want to pass it to PayPal and display it on the hosted payment page again. This information will be pre-filled and editable on this 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.

 Customer Name - Buyer's first and last name  Billing Address - Buyer's billing address  Billing Phone Number - Buyer's phone number  Billing Email Address - Buyer's email address  Postal Address - Buyer's shipping address.

Buyer Authentication Program

Customising Your PayPal Payment Page

Modifying Your PayPal Account Settings

You can check Maestro, Visa, and MasterCard card types for enrollment in a buyer authentication program like 3-D Secure. 3-D Secure implementation such as Verified by Visa or MasterCard SecureCode is an additional form of authentication which provides a credit and debit card holder another layer of security while paying for online purchases. This deters the unauthorised use of the buyer’s credit or debit card during online purchases and also reduces the chargeback rate for the merchants implementing this scheme.

NOTE: It is mandatory that Maestro is checked for enrollment in the buyer authentication

program.

After selecting a card type to check for enrollment, you can also choose to accept transactions that are not protected by buyer authentication (transactions that do not pass the 3-D Secure check). You have the following options for such transactions:

 Yes - PayPal processes these transactions as non-buyer authentication transactions.  No - PayPal rejects these transactions.

Customising Your PayPal Payment Page

Modifying Your PayPal Account Settings

Payment Confirmation Page

Once the transaction is successful, you can choose to display your payment confirmation on either a PayPal's confirmation page or on your own payment confirmation page.

 On a PayPal page that shows the payment is complete - The payment confirmation

appears on the PayPal confirmation page. Optionally, you can also provide a URL on the confirmation page to take your buyer back to your website. To do so, enter the appropriate URL in the field provided.

 On the Company's confirmation page - The payment confirmation will appear on your

own payment confirmation page. For this, enter the URL of the page that will display the payment confirmation. You will have to message the outcome of the transaction to the buyer when PayPal redirects back to this URL. Be sure to display specifics of the order so the buyer sees a meaningful confirmation. You can get the specifics of the order using the Transaction ID we pass back to you with the return URL.

Design

Customising Your PayPal Payment Page

Modifying Your PayPal Account Settings

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 two design templates or layouts for you to choose from. Template or Layout A is the default template, however, you can choose either templates.

NOTE: Your buyers will not see the payment page until you have completed the HTML

integration with your website.

Preview the design of your payment page. You can either change the design of your template, or select and customise a different template on this page. To make changes, left-click on the section you are trying to modify or the corresponding Click to Edit button for that section. On the pop-up that appears, click the color selector to change the color, or enter the appropriate URL, as needed.

If the buyer pays by logging into PayPal, the look and feel of that flow can be customised through the customisation options on the Profile page.

After making the changes, click one of the following buttons:

 Preview - Preview the changes you have made to your template before saving and

publishing it.

 Save and Publish - Save all the changes you have made and publish the updated template.

Your buyers will see the updated payment page.

 Cancel - Discard all the changes you have made in this session.  Undo Changes - Discard all changes you have made since the last time you saved the

template. Your buyers will see the last saved template.

NOTE: You must make all modifications (including changing templates) within the same

session, otherwise all changes will be lost and you will have to redo your changes. If the session times out, the design of the template will remain at the version that was last published.

+ 51 hidden pages