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.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . .
P 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.
P 6 Preface Documentation Feedback
1 Getting Started with Website Payments Pro Hosted Solution 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.
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.
Getting Started with Website Payments Pro Hosted Solution Introduction to Integrating with Hosted Solution 10
2 Integrating Your Website Using HTML This chapter provides instructions for a simple integration that enables you to begin processing transactions using Hosted Solution. N O T E : 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.
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.
Integrating Your Website Using HTML HTML Variables 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 address1 Street name of shipping address.
Integrating Your Website Using HTML HTML Variables TABLE 2.1 HTML Variables for Settings of Payment Page (Continued) Variable Description Mandatory custom A free-form field for your own use. This variable is never presented to the buyer and will be returned in IPN messages. No discount Shipping discount for this order. Specify the discount as a positive amount. Nine numeric characers plus decimal (.) character. No currency symbol. Specify the exact amount to the cent using a decimal point—use 34.
Integrating Your Website Using HTML HTML Variables TABLE 2.1 HTML Variables for Settings of Payment Page (Continued) Variable Description Mandatory paymentaction Indicates whether the transaction is for payment on a final sale or an authorisation for a final sale (to be captured later). Allowable Values: - authorization or sale Default Value - sale Yes return The URL to which the buyer’s browser is redirected to after completing the payment.
Integrating Your Website Using HTML HTML Variables 16
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 O T E : HTML variables will override the settings you save on your profile 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.
Customising Your PayPal Payment Page Modifying Your PayPal Account Settings Buyer Authentication Program 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.
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. 20 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.
Customising Your PayPal Payment Page Modifying Your PayPal Account Settings Design
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.
Customising Your PayPal Payment Page Modifying Your PayPal Account Settings Choosing a Layout Choose from the following two design templates or layouts: Template A Template B 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 Customising Your Layout Consider the following when you customise your template: Header (applicable to Template A and B) - 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 Hosted Solution HTML variables you can use to customise the look and feel of your payment page. TABLE 3.1 HTML Variables for Look and Feel of Payment Page 26 Variable Description bodyBgColor Color of the surrounding background of the payment page. bodyBgImg Image of the surrounding background of the payment page. The file extension can be .gif, .jpg, .jpeg, or .png format.
Customising Your PayPal Payment Page Adding HTML Variables TABLE 3.1 HTML Variables for Look and Feel of Payment Page 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.
Customising Your PayPal Payment Page Adding HTML Variables 28
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: HTML 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 4. Submit the form using JavaScript. For example: Example of Manual Integration The complete example as per the above steps is as follows:
5 Integrating Your Website Using API Using the Button Manager API, you can programmatically create the checkout button that initiates the Hosted Solution checkout flow on your website. You create the checkout button dynamically when the buyer attempts to checkout on your website. When the buyer clicks on your checkout button, you call the BMCreateButton API operation to create a checkout button and display it on your web page.
Integrating Your Website Using API Using the Button Manager API with Hosted Solution Checkout Using the Button Manager API with Hosted Solution Checkout N O T E : Before using the Button Manager API, you must acquire PayPal API credentials. For more information, refer to Appendix A, “Obtaining API Credentials. To create a checkout button on your website, you call the BMCreateButton API operation. When the buyer clicks on the checkout button, PayPal initiates the Hosted Solution checkout flow.
Integrating Your Website Using API Using the Button Manager API with Hosted Solution Checkout Example of TOKEN EMAILLINK=https://securepayments.paypal.com/cgi-bin/webscr?cmd=_sxclick&hosted_button_id=HSS-1PncRuoWdOkE2cDn3bIsTr-5ODQUxac&HOSTEDBUTTONID=HSS-1PncRuoWdOkE2cDn3bIsTr-5ODQU-xac&TIMESTAMP=2011-0817T22:58:45Z&CORRELATIONID=5366c981124b1&ACK=Success&VERSION=65.0&BUILD=206 6255 Example of ENCRYPTED EMAILLINK=https://securepayments.paypal.
Integrating Your Website Using API Using the Button Manager API with Hosted Solution Checkout Identify the WEBSITECODE in the response and use the code to create a Pay Now button on your review page. When your buyer clicks the button, they are redirected to the PayPal hosted payment page. Like the URL, the button is usable for approximately two hours or until the payment is successful. N O T E : PayPal recommends using TOKEN or ENCRYPTED.
Integrating Your Website Using API Using the Button Manager API with Hosted Solution Checkout 
N O T E : The PayPal payment page displays a button identified as Pay Now to complete the checkout flow.
Integrating Your Website Using API Using the Button Manager API with Hosted Solution Checkout
Integrating Your Website Using API Using the Button Manager API with Hosted Solution Checkout PAGE 42
Integrating Your Website Using API BMCreateButton API Operation BMCreateButton API Operation Use the BMCreateButton API operation to create Hosted Solution checkout button. BMCreateButton Request BMCreateButton Response BMCreateButton Errors BMCreateButton Request The request fields specify the characteristics of your button, which include associated menu items related to the button. You can specify up to 5 menu items, each of which can include up to 10 possible selections.
Integrating Your Website Using API BMCreateButton API Operation BMCreateButton Errors Error Code Short Message Long Message 10001 Internal Error Internal Error 11923 Invalid Argument The button image value specified is invalid. 11924 Invalid Argument The button image URL specified is invalid. 11925 Invalid Argument The button type specified is invalid. 11926 Invalid Data One of the parameters specified using ButtonVar is invalid.
Integrating Your Website Using API BMCreateButton API Operation 44
6 Order Processing This chapter walks you through the end to end order processing experience. It includes information about verifying the status and authenticity of the order before fulfilling it.
Order Processing Fulfilling Order 46
A Obtaining API Credentials To use the PayPal APIs, you must have API credentials that identify you as a PayPal account holder who is authorized to perform various API operations. Although you can use either an API signature or a certificate, PayPal recommends you use a signature. IMPO RTANT: Although you have both a signature and a certificate, you cannot use both at the same time.
Obtaining API Credentials Encrypting Your Certificate Into PKCS12 Format 4. Under Option 2, click View API Signature. 5. Save the values for API Username and API Password, and click Done. 6. Click Download Certificate and save the file. 7. Rename the file to something familiar, such as paypal_live_cert.pem. It is not necessary to keep the .txt file extension. Be sure to remember where you save the file. After completing this task: If you use the PayPal SDK for Java, the PayPal SDK for .
Obtaining API Credentials Importing Your Certificate Importing Your Certificate For either PayPal SDK for .NET or Classic ASP, you must download and execute the Windows HTTP Services Certificate Configuration Tool, WinHTTPCertCfg. If you use the .NET platform and develop with the PayPal SDK for .NET, you need to take a few more steps before your certificate can be used.
Obtaining API Credentials Importing Your Certificate 50
B Error Messages The table below lists error codes and the appropriate correction action. TABLE B.1 Error Codes and the Corresponding Corrective Actions Error Code Error Message Corrective Action (if applicable) 1 User authentication failed. Error is caused by one or more of the following: Login information is incorrect. Verify that USER, VENDOR, PARTNER, and PASSWORD have been entered correctly. VENDOR is your merchant ID and USER is the same as VENDOR unless you created a Payflow Pro user.
Error Messages TABLE B.1 Error Codes and the Corresponding Corrective Actions(Continued) Error Code Error Message Corrective Action (if applicable) 11 Client time-out waiting for response 12 Declined Check the credit card number, expiration date, and transaction information to make sure they were entered correctly. If this does not resolve the problem, have the customer call their card issuing bank to resolve. 13 Referral.
Error Messages TABLE B.
Error Messages TABLE B.1 Error Codes and the Corresponding Corrective Actions(Continued) Error Code Error Message Corrective Action (if applicable) 108 Void error. See RESPMSG. Make sure the transaction ID entered has not already been voided. If not, then look at the Transaction Detail screen for this transaction to see if it has settled. (The Batch field is set to a number greater than zero if the transaction has been settled).
Error Messages TABLE B.1 Error Codes and the Corresponding Corrective Actions(Continued) Error Code Error Message 119 General failure within PIM Adapter 120 Attempt to reference a failed transaction 121 Not enabled for feature 122 Merchant sale total will exceed the credit cap with current transaction. ACH transactions only.
Error Messages TABLE B.1 Error Codes and the Corresponding Corrective Actions(Continued) Error Code Error Message 200 Reauth error 201 Order error 402 PIM Adapter Unavailable 403 PIM Adapter stream error 404 PIM Adapter Timeout 600 Cybercash Batch Error 601 Cybercash Query Error 1000 Generic host error.
Error Messages TABLE B.1 Error Codes and the Corresponding Corrective Actions(Continued) Error Code Error Message Corrective Action (if applicable) 1017 Buyer Authentication Service — 3-D Secure error response is invalid. An error response is received and the response is not well formed for a Validate Authentication transaction.
Error Messages TABLE B.
Error Messages TABLE B.1 Error Codes and the Corresponding Corrective Actions(Continued) Error Code Error Message Corrective Action (if applicable) 10009 Your payment can't be processed. Please contact the merchant directly with this code. Try again later. 10010 Your payment can't be processed. Please contact the merchant directly with this code. Provide a valid invoice ID. 10413 Your payment can't be processed. Please contact the merchant directly with this code.
Error Messages TABLE B.1 Error Codes and the Corresponding Corrective Actions(Continued) Error Code Error Message Corrective Action (if applicable) 10511 Your payment can't be processed. Please contact the merchant directly with this code. Review the integration to ensure that a valid PaymentAction value is supplied. 10512 Please enter a first name. First name of the buyer is required. 10513 Please enter a last name. Last name of the buyer is required. 10520 Your payment can't be processed.
Error Messages TABLE B.1 Error Codes and the Corresponding Corrective Actions(Continued) Error Code Error Message Corrective Action (if applicable) 10540 Please enter a valid address. Transaction was declined by PayPal because of an invalid address. Buyer should provide the correct address. 10541 Please enter a valid credit card number. Credit card entered is currently restricted by PayPal. Contact PayPal with this error code. 10542 Please enter a valid email address.
Error Messages TABLE B.1 Error Codes and the Corresponding Corrective Actions(Continued) Error Code Error Message Corrective Action (if applicable) 10553 Your payment can't be processed. Please contact the merchant directly with this code. Merchant attempted a transaction where the amount exceeded the upper limit for that merchant. 10554 Your payment can't be processed. Please contact the merchant directly with this code. Transaction was declined because of a risk filter for AVS.
Error Messages TABLE B.1 Error Codes and the Corresponding Corrective Actions(Continued) Error Code Error Message Corrective Action (if applicable) 10565 Your payment can't be processed. Please contact the merchant directly with this code. Merchant country is not supported. 10566 Your payment can't be processed. Please pay with a different card type. Credit card type is not supported. 10567 Please enter an issue number or a start date. Buyer should enter an issue number or a start date.
Error Messages TABLE B.1 Error Codes and the Corresponding Corrective Actions(Continued) Error Code Error Message Corrective Action (if applicable) 10713 Please enter a country in the billing address. Buyer should enter a country in the billing address. 10714 Please enter a valid name in the billing address. Buyer should enter a valid name in the billing address. 10715 Please enter a valid state in the billing address. Buyer should enter a valid state in the billing address.
Error Messages TABLE B.1 Error Codes and the Corresponding Corrective Actions(Continued) Error Code Error Message Corrective Action (if applicable) 10729 Please enter a state in the shipping address. Buyer should enter a state in the shipping address. 10730 Please enter a postal code in the shipping address. Buyer should enter a valid postal code in the shipping address. 10731 Please enter a country in the shipping address. Buyer should enter a country in the shipping address.
Error Messages TABLE B.1 Error Codes and the Corresponding Corrective Actions(Continued) Error Code Error Message Corrective Action (if applicable) 10752 Your payment can't be processed. Please pay with another card. Transaction was declined by the issuing bank, not PayPal. Buyer should attempt another card. 10754 Your payment can't be processed. Please pay with another card. Buyer should use a different credit card. 10755 Your payment can't be processed.
Error Messages TABLE B.1 Error Codes and the Corresponding Corrective Actions(Continued) Error Code Error Message Corrective Action (if applicable) 12000 Your payment can't be processed. Please contact the merchant directly with this code. This is related to insufficient 3DS parameters. Contact PayPal with this error code. 12001 Your payment can't be processed. Please contact the merchant directly with this code. This is related to insufficient 3DS parameters. Contact PayPal with this error code.
Error Messages 68
C Currency Codes The table below lists all the currencies supported by PayPal. TABLE C.1 Currency Codes Currency Code Country Name AUD Australian Dollar CAD Canadian Dollar CHF Swiss Franc CZK Czech Koruna DKK Danish Krone EUR Euro GBP British Pound Sterling HKD Hong Kong Dollar HUF Hungarian Forint JPY Japanese Yen NOK Norwegian Krone NZD New Zealand Dollar PLN Polish Zloty SEK Swedish Krona SGD Singapore Dollar USD U.S.
Currency Codes 70
Index Numerics 3-D Secure 7, 19 BUTTONCODE=TOKEN 35 BUTTONTYPE 42 BUTTONTYPE=PAYMENT 35 buyer_email 13 A address_override 13 address1 13 address2 13 API integration 35 B background 25 billing_address1 13 billing_address2 13 billing_city 13 billing_country 13 billing_first_name 13 billing_last_name 13 billing_state 13 billing_zip 13 BMCreateButton API 35, 36, 42 BMCreateButton API Operation 42 BMCreateButton Errors 43 BMCreateButton Request 42 BMCreateButton Request Fields 42 BMCreateButton Response 42 B
Index headerHeight 26 HOSTED 35 HOSTEDBUTTONID 42 HTML integration 11 HTTP variables 13, 26 I iFrames 29 API integration 31 manual integration 30 Instant Payment Notification (IPN) 45 integration API 35 HTML 11 invoice 14 orderSummaryBgImage 26 overview 7 P pageButtonBgColor 26 pageButtonTextColor 26 pageTitleTextColor 26 paymentaction 15 PCI complicance 7 preview 22 private key 39 public key 39 R return 15 L L_BUTTONVAR 42 last_name 14 lc 14 logoFont 26 logoFontColor 26 logoFontSize 26 logoImage 26 l
Index W WEBSITECODE 32, 38, 42 Z zip 15 73
