Website Payments Standard Checkout Integration Guide For Professional Use Only Currently only available in English. A usage Professional Uniquement Disponible en Anglais uniquement pour l'instant.
PayPal Website Payments Standard Checkout Integration Guide © 2006 PayPal Inc. All rights reserved. PayPal and the PayPal logo are registered trademarks of PayPal, Inc. Designated trademarks and brands are the property of their respective owners. Notice of Non-Liability PayPal, Inc. and the authors assume no liability for errors or omissions, or for damages, resulting from the use of this Manual or the information contained in this Manual.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Chapter 1 How Website Payments Standard Works . . . . . . . . . . 15 Example of the Basic Page Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 How You Get Your Money . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Notifications You Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Adding Your Credit Card Statement Name . . . . . . . . . . . . . . . . . . . . . . . . . 49 Getting Customer Contact Telephone Numbers . . . . . . . . . . . . . . . . . . . . . . . 49 Language Encoding Your Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Multi-User Access to Your PayPal Account . . . . . . . . . . . . . . . . . . . . . . . . . 55 PayPal-Supported Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 . . . . . . . . . . . . . . . . . .
Contents Downloading PayPal's Public Certificate. . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Removing Your Public Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Blocking Unencrypted Website Payments . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Chapter 6 Testing in the PayPal Sandbox . . . . . . . . . . . . . . . 89 Chapter 7 Website Payments Standard HTML FORM Basics . . . . . . 91 FORM Attributes: ACTION and METHOD . . . . . . . . . . . . . . . . . .
Contents 6 November 2005
List of Tables Table 1.1 How To Use This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Table 1.2 Hyperlinks for Fees, Security, User Agreement, Policies, Online Help, and Customer Service 24 Table 1.3 PayPal Technical Documentation . . . . . . . . . . . . . . . . . . . . . 25 Table 2.1 Order of Page Style Customization Variables . . . . . . . . . . . . . . . 33 Table 2.2 PayPal-Supported Currencies, Currency Codes, and Maximum Transaction Amounts 56 Table 4.
List of Tables 8 November 2005Website Payments Standard Checkout Integration Guide
List of Figures Figure 1.1 Basic Website Payments Standard Page Sequence Figure 1.2 Beginning of Basic Page Sequence on Your Website . . . . . . 16 Figure 1.3 Customer Logs In to or Signs Up for PayPal Figure 1.4 Customer Reviews Payment . . . . . . . . . . . . . . . . . 18 Figure 1.5 Payment Confirmation or “You Made a Payment” Page on PayPal 19 Figure 1.6 Customer Returns to Your Website Figure 1.7 Account History: Recent Activity . . . . . . . . . . . . . . . 21 Figure 2.
List of Figures 10 Figure 4.7 Third-Party Shopping Cart Example: Proceed to Checkout . . . 77 Figure 4.8 Third-Party Shopping Cart Example: Logging In to PayPal during Checkout 78 Figure 4.9 Third-Party Shopping Cart Example: Confirmation Page . . . . 79 Figure 4.10 Shopping Cart Example: Thank You Page After Payment Figure 4.11 Example: Email Transaction Receipt . . . . . . . . . . . . . 80 Figure 4.12 Example: Seller’s Email Receipt . . . . . . . . . . . . . . . 81 Figure 5.
List of Examples Example 2.1 Flat Amount Shipping Calculation . . . . . . . . . . . . . . . . . . . . . 46 Example 2.2 Percentage Shipping Calculation . . . . . . . . . . . . . . . . . . . . . . 46 Example 3.1 HTML for Buy Now Button . . . . . . . . . . . . . . . . . . . . . . . . . 65 Example 4.1 HTML for PayPal-Hosted Shopping Cart “Add to Cart” Button . . . . . . . 75 Example 4.1 HTML for Passing Individual Item Detail to PayPal . . . . . . . . . . . . . 83 Example 4.
List of Examples 12 November 2005 Website Payments Standard Checkout Integration Guide
Preface This Document This document, the PayPal Website Payments Standard Checkout Integration Guide, is a complete revision of the version issued in September 2005. Intended Audience This document is for merchants whose websites obtain payments using PayPal features. Notational Conventions This document uses typefaces to identify the characteristics of text. These typefaces and the characteristics they imply are described below: Typeface How Used serif italics A document title.
Preface To convey additional information, this document may also apply color and underlining to words or phrases that use the typefaces described above. Such use is described below: Text attribute How Used xxxxxx Hypertext link to a page in the current document or to another document in the set. xxxxxx Hypertext link to a URL or that initiates a web action, such as sending mail.
1 How Website Payments Standard Works The PayPal Website Payments Standard Checkout Integration Guide describes how you use Website Payments Standard. Website Payments Standard consists of HTML FORMs on your website that direct your customer’s web browser to the PayPal website at http://www.paypal.com in order to pay you and then return the customer to your website. Figure 1.
1 How Website Payments Standard Works Example of the Basic Page Sequence Example of the Basic Page Sequence Here’s an example of the basic page sequence of Website Payments Standard. Like all examples of pages in this guide, this example is based on the PayPal sample integration, which demonstrates how PayPal has been integrated with the fictitious online store called “DesignerFotos.” BEGIN. The customer chooses to pay with PayPal on your website. FIGURE 1.
How Website Payments Standard Works Example of the Basic Page Sequence 1 The customer logs in to PayPal. FIGURE 1.3 Customer Logs In to or Signs Up for PayPal If the customer were new to PayPal, the customer could choose to sign up for a PayPal account.
1 How Website Payments Standard Works Example of the Basic Page Sequence On PayPal, the customer reviews the details of the payment and makes the payment. FIGURE 1.4 Customer Reviews Payment At this point, the customer can choose among funding sources (credit cards, debit cards, or bank accounts recorded in the PayPal accounts) with which to pay you and can also choose among shipping addresses stored on PayPal. This example does not show the pages containing these options.
How Website Payments Standard Works Example of the Basic Page Sequence 1 The customer sees a payment confirmation page on PayPal and clicks Return to Merchant. FIGURE 1.
1 How Website Payments Standard Works Example of the Basic Page Sequence END. The customer is returned to your website. FIGURE 1.
How Website Payments Standard Works How You Get Your Money 1 How You Get Your Money After a customer makes a payment, your PayPal account lists the payment in your Account History, as shown below. FIGURE 1.7 Account History: Recent Activity Notifications You Receive You can be notified of payments in four ways: email, History Log, Downloadable History Log, and Instant Payment Notification (IPN).
1 How Website Payments Standard Works Notifications You Receive 3. Under the Payment Notifications heading, clear the I receive PayPal Website Payments and Instant Purchase checkbox. 4. Click Save. Transaction History Your transaction history (also called your “History) displays information about your payments.
How Website Payments Standard Works How To Use This Guide 1 How To Use This Guide Website Payments Standard has two primary components: Buy Now or Donations buttons and Shopping Cart. Both are constructed with the same basic set of HTML FORM variables. You can affect their behavior and appearance with settings in your account Profile and with additional FORM variables. The following table summarizes the contents of this guide. TABLE 1.1 How To Use This Guide Feature Description See Also...
1 How Website Payments Standard Works Related Online Information z z Instant Payment Notification (IPN) and Payment Data Transfer (PDT) are HTML FORMbased mechanisms to send information about payments to programs on your website. IPN and PDT are described in the Order Management Integration Guide.
How Website Payments Standard Works Complementary Documentation 1 Complementary Documentation All PayPal technical documentation is listed here. The description of each guide indicates its subject matter and documentation necessary for effective use of the guide. TABLE 1.3 PayPal Technical Documentation Guide Title Description Prerequisites Website Payments Standard Integration Guide Details basic PayPal payment process for shopping cart and single-item purchase.
1 How Website Payments Standard Works Complementary Documentation TABLE 1.3 PayPal Technical Documentation Guide Title Description Prerequisites Java SDK Guide .NET SDK Guide Classic ASP Guide PHP SDK Guide Details the use of the PayPal Software Development Kits for Java, Microsoft .NET, Microsoft Classic ASP, and PHP to simplify use of the PayPal Web Services API. https://www.paypal.com/en_US/pdf/PP_SDK_Java_Guide.pdf https://www.paypal.com/en_US/pdf/PP_SDK_NET_Guide.pdf https://www.paypal.
2 Using Your Merchant Account Profile and Tools This chapter details how you can use your account Profile settings and other tools on the PayPal website to affect how payments are processed. The Account Profile Summary Use your PayPal account Profile to manage information about your PayPal account. To see your Profile, log in to your PayPal account, and click the Profile subtab of the My Account tab. The Profile has three sections: Account Information, Financial Information, and Selling Preferences.
2 Using Your Merchant Account Profile and Tools The Account Profile Summary Account Information Use the Account Information column for basic account maintenance, including updating your password, adding and confirming email addresses, managing your business information, and (for Premier accounts) configuring multi-user access to your PayPal account.
Using Your Merchant Account Profile and Tools Branding PayPal’s Payment Pages 2 Branding PayPal’s Payment Pages With our Custom Payment Pages feature, you can tailor PayPal’s payment pages to the style of your website. Custom Payment Pages work with all PayPal Website Payment buttons and with the PayPal Account Optional feature. You can add up to three custom page styles. The pictures in this section demonstrate the types of customization you can add to your PayPal Website Payment buttons. Figure 2.
2 Using Your Merchant Account Profile and Tools Branding PayPal’s Payment Pages Figure 2.3, “Complete Custom Page Style,” shows all the customization you can make. FIGURE 2.
Using Your Merchant Account Profile and Tools Branding PayPal’s Payment Pages 2 Working with Custom Payment Pages 1. Log in to your PayPal account at https://www.paypal.com. 2. Click the Profile subtab. 3. In the Selling Preferences column, click Custom Payment Pages. The customization page shown in Figure 2.4, “Edit Custom Page Style Page,” is displayed. FIGURE 2.
2 Using Your Merchant Account Profile and Tools Branding PayPal’s Payment Pages Adding or Editing a Page Style The settings described here can also be specified with HTML FORM input variables set for individual transactions. For more information, see Table A.4, “HTML Variables: Display Information” on page 100. To add a page style: 1. Begin at the Custom Payment Page Styles page. 2. Click Add or Edit. 3.
Using Your Merchant Account Profile and Tools Branding PayPal’s Payment Pages 2 About Font Colors. PayPal dynamically changes font colors from black to white, depending on the background color. To confirm that these font changes comply with your font color selections, you should test your color settings on PayPal. Making a Page Style Primary When you make a page style primary, it is applied to all payment pages unless you specify otherwise on individual transactions.
2 Using Your Merchant Account Profile and Tools Streamlining Purchases with Website Payment Preferences Streamlining Purchases with Website Payment Preferences You can speed up your customers’ purchases with three Profile settings: z Account Optional z Auto Return z Automatic calculation of shipping and handling cost and taxes These settings are part of the Website Payment Preferences of your account Profile Selling Preferences. FIGURE 2.
Using Your Merchant Account Profile and Tools Streamlining Purchases with Website Payment Preferences 2 Account Optional or Website Payments Express Account Optional (also known as Website Payments Express) is a Profile setting that allows customers new to PayPal to pay you by credit card without signing up for a PayPal account, thus shortening their time and effort. Customers who have PayPal accounts go through the same Website Payments page sequence shown in Figure 1.
2 Using Your Merchant Account Profile and Tools Streamlining Purchases with Website Payment Preferences Turning PayPal Account Optional On or Off 1. Log in to your PayPal account at https://www.paypal.com. 2. Click the Profile subtab. 3. Click the Website Payment Preferences link in the Selling Preferences column. See Figure 2.5, “Website Payment Preferences on the Profile Summary Page” on page 34. 4. Scroll down to the PayPal Account Optional section of the page. 5.
Using Your Merchant Account Profile and Tools Streamlining Purchases with Website Payment Preferences 2 Step 2: Bob is taken to a Payment Details page. He is prompted to log in to his PayPal account. He is not a PayPal member, so he clicks Secure Checkout.
2 Using Your Merchant Account Profile and Tools Streamlining Purchases with Website Payment Preferences Step 3: Bob is prompted to enter the shipping information for the purchase, and to indicate if his shipping address is the same as the billing address on his credit card. Accepting the default selection of Yes, Bob clicks Continue Checkout and is taken to the page shown in Step 4.
Using Your Merchant Account Profile and Tools Streamlining Purchases with Website Payment Preferences 2 Step 4: Bob is prompted to enter billing information for the credit card for the purchase.
2 Using Your Merchant Account Profile and Tools Streamlining Purchases with Website Payment Preferences Step 5: Bob is taken to a review page. He clicks Pay to complete his purchase.
Using Your Merchant Account Profile and Tools Streamlining Purchases with Website Payment Preferences 2 Step 6: Bob is taken to a payment completion page where he sees the Receipt ID for this transaction and DesignerFoto’s customer service contact information. If Bob clicks Save My Info, he is taken to a page where he can enter the rest of the information needed to create a PayPal account (see Step 7). The information Bob entered to complete the transaction is carried forward.
2 Using Your Merchant Account Profile and Tools Streamlining Purchases with Website Payment Preferences Step 7: If Bob clicked Save My Info, he is taken to a page where he can complete signing up for a PayPal account. Once he has filled in the fields, he clicks Save Information to create the account. Step 8: Bob sees a page that confirms the creation of his account.
Using Your Merchant Account Profile and Tools Streamlining Purchases with Website Payment Preferences 2 Step 9: Bob receives an email receipt that confirms his payment and includes a copy of the payment details for this transaction. Auto Return With Auto Return for Website Payments, you can avoid making your customers click an extra button before returning to your website after completing a payment.
2 Using Your Merchant Account Profile and Tools Streamlining Purchases with Website Payment Preferences FIGURE 2.7 Momentary “You Made a Payment Page” with Auto Return On Turning On Auto Return To turn Auto Return on: 1. Log in to your PayPal account at https://www.paypal.com. 2. Click the Profile subtab. 3. Under the Selling Preferences column, click Website Payment Preferences. See Figure 2.5, “Website Payment Preferences on the Profile Summary Page” on page 34. 4.
Using Your Merchant Account Profile and Tools Streamlining Purchases with Website Payment Preferences 2 N O T E : If the Return URL you supply is not valid, PayPal displays the standard You Made a Payment page when payment is complete. 6. Click Save. Setting Return URL on Individual Transactions With Auto Return turned on in your Profile, you can set the value of the return URL on each individual transaction, overriding the value you have stored on PayPal.
2 Using Your Merchant Account Profile and Tools Streamlining Purchases with Website Payment Preferences With the radio buttons, you can apply tax either to the item itself or to an item and any shipping and handling costs. Click Save to save your changes. Overriding Tax Setting on Individual Transactions Regardless of a customer’s location, you can set a flat tax amount on an individual transaction or items in the transaction. For more information, see “Setting the Tax for the Entire Cart” on page 83.
Using Your Merchant Account Profile and Tools Blocking Certain Kinds of Payment 2 charge a different shipping amount for an item, include the shipping cost in the shipping and handling_cart variables in the HTML FORM for the button. You must set your Profile to allow individual transactions to override the Profile shipping calculation settings: 1. Go to the Shipping Calculations page in your Profile. 2.
2 Using Your Merchant Account Profile and Tools Blocking Certain Kinds of Payment to take on the risk of not having the buyer’s Confirmed Address for each transaction. If you accept the payment, it becomes a completed transaction. If you deny a particular payment, the sender of the payment is notified that the payment has been denied and is credited with the payment amount. PayPal does not charge fees for denied payments.
Using Your Merchant Account Profile and Tools Adding Your Credit Card Statement Name 2 they pay with a credit card. Users who have not confirmed their bank accounts with PayPal can still send you money funded by credit cards. Blocking Payments Funded By eChecks You can block eCheck payments. Because eCheck payments take three to four business days to clear, you might want to block them for your Instant Purchase and Buy Now buttons.
2 Using Your Merchant Account Profile and Tools Language Encoding Your Data IMPO RTANT: In accordance with PayPal’s User Agreement, you may use this Contact Telephone Number only to communicate with the buyer about the related purchase. You may not use this number for unsolicited commercial messages. You can make the contact telephone number optional or required, or you can turn it off.
Using Your Merchant Account Profile and Tools Language Encoding Your Data 2 letterforms, numbers, punctuation, and symbols of American English. Another example of a character set is Big 5, which is one of the most widely implemented Chinese character sets. Character encoding, on the other hand, refers to how a particular character set is represented internally in data processing; that is, how the individual characters are actually stored and operated on. There many different kinds of character encodings.
2 Using Your Merchant Account Profile and Tools Language Encoding Your Data Changing Your Website Language The Language Encoding page displays the setting for your website’s language, as shown in the following illustration. With the Your website’s language drop-down menu, you change the setting. FIGURE 2.
Using Your Merchant Account Profile and Tools Language Encoding Your Data 2 FIGURE 2.13 Website Language Preference Click Save to save your selection or Cancel to leave the setting unchanged. More Encoding Options If you want to specify the exact standard name of your website’s character encoding, click More Options on the Language Encoding page to open the More Encoding Options page shown in Figure 2.14, “More Language Encoding Options.
2 Using Your Merchant Account Profile and Tools Language Encoding Your Data FIGURE 2.14 More Language Encoding Options The encoding selection in the Encoding drop-down menu is based on the country of origin you specified at signup. To change the encoding selection, click the Encoding drop-down menu and select one of the available encodings. For a complete list of supported encodings, see “Table 7.2, “Character Sets and Encodings Supported by PayPal” on page 93.
Using Your Merchant Account Profile and Tools Multi-User Access to Your PayPal Account 2 Multi-User Access to Your PayPal Account With Multi-User Access, you can set up multiple logins with different permissions for business functions in your PayPal account, so employees have access only to the parts of your account they need to do their work.
2 Using Your Merchant Account Profile and Tools PayPal-Supported Currencies FIGURE 2.16 Multi-User Access: Adding a User PayPal-Supported Currencies The following currencies are supported by PayPal. TABLE 2.
Using Your Merchant Account Profile and Tools TABLE 2.2 2 PayPal-Supported Currencies, Currency Codes, and Maximum Transaction Amounts Code Currency Maximum Transaction Amount GBP Pound Sterling 5,500 GBP JPY Japanese Yen 1,000,000 JPY USD U.S. Dollar 10,000 USD Accepting or Denying Cross-Currency Payments You choose which currencies you accept and how you would like to accept them. You can set your Payment Receiving Preferences to handle cross-currency payments.
2 Using Your Merchant Account Profile and Tools Issuing Refunds Managing Currency Balances Use the Currency Balances section of your Profile to manage your currency balances: z Select your primary currency z Open or close a currency balance z Transfer funds between currency balances. Funds transferred from one currency balance to another are exchanged at a competitive rate. Issuing Refunds When you issue a refund, the gross amount of the refund is sent to your customer.
Using Your Merchant Account Profile and Tools Issuing Refunds 2 3. Enter the required information. 4. Click Continue. 5. Review the information on the confirmation page, and click Send Money to complete the refund.
2 60 Using Your Merchant Account Profile and Tools Issuing Refunds November 2005 Website Payments Standard Checkout Integration Guide
3 Single-Item Payment: Buy Now and Donations Buy Now or Donations buttons are suitable for single-item payments or purchases. A single Buy Now button can sell one or more copies of the same item. However, to sell different items you must create separate Buy Now Buttons for each or use PayPal’s Shopping Cart. You can use to a Donations button to collect a pre-determined amount, or you can allow your donors to choose the amounts of their donations.
3 Single-Item Payment: Buy Now and Donations Using Buy Now or Donations Button Factory Donations Button Fields – Donation Name/Service: Enter the reason for payment or the name of your organization/charity here. If you do not enter anything in this field, your donors can complete this field. – Donation ID/Number: You can use this field to differentiate payments (e.g. to enter a campaign name).
Single-Item Payment: Buy Now and Donations Using Buy Now or Donations Button Factory 3 Adding More Details to the Button If you do not have additional details to add to your button (such as sales tax, shipping, or your logo), click Create Button Now and go to “Copy and Paste the HTML Code” on page 64. Otherwise, click Add More Options. If you have additional details for your button, follow these steps: 1.
3 Single-Item Payment: Buy Now and Donations Using Buy Now or Donations Button Factory return to the Successful Payment URL you have specified. If you do not enter a Successful Payment URL, customers clicking this link are taken to a PayPal webpage. – Cancel Payment URL: Enter the URL where you want to send your customers if they cancel their payments at any point in the Buy Now payment flow. If you do not enter a Cancel Payment URL, customers who click this link are taken to a PayPal webpage. 5.
Single-Item Payment: Buy Now and Donations Sample Buy Now Button HTML and Hyperlink 3 1. Copy the code from the Link for Emails text box by highlighting all of the text and pressing Ctrl+C, or by highlighting all of the text, right-clicking your mouse, and choosing Copy. 2. Open the email you want to send. 3. Paste the code you just copied into your email either by pressing Ctrl+V or by rightclicking on your mouse and selecting the Paste option. 4.
3 Single-Item Payment: Buy Now and Donations Sample Buy Now Button HTML and Hyperlink
4 Multiple-Item Payment: Shopping Cart With PayPal’s Shopping Cart, your customers can buy multiple items with a single payment, browse your entire selection, and view a consolidated list of all their items before purchasing. The shopping cart comes in two basic forms: 1. A shopping cart hosted on the PayPal website, https://www.paypal.com/. 2. HTML input variables for use in third-party shopping carts.
4 Multiple-Item Payment: Shopping Cart How the PayPal-Hosted Shopping Cart Works What The Customer Sees Bob, who has a PayPal account, is buying from The Stuff Shop. He selects a baseball hat by clicking Add to Cart. FIGURE 4.1 PayPal-Hosted Shopping Cart Example: Add to Cart The Stuff Shop is using a generic Add to Cart button created with the PayPal shopping cart button factory described in “Button Factory for PayPal-Hosted Shopping Cart” on page 72.
Multiple-Item Payment: Shopping Cart How the PayPal-Hosted Shopping Cart Works 4 Bob’s browser is redirected to the PayPal website enters his PayPal username and password, and clicks Log In. FIGURE 4.
4 Multiple-Item Payment: Shopping Cart How the PayPal-Hosted Shopping Cart Works Bob is taken to a confirmation page showing the details of his payment. FIGURE 4.3 PayPal-Hosted Shopping Cart Example: Confirmation Page Because The Stuff Shop has not activated Profile-based shipping preferences, no shipping costs are added to the order. For information about automatic shipping calculation, see “Automatic Calculation of Shipping and Handling Cost and Tax” on page 45.
Multiple-Item Payment: Shopping Cart How the PayPal-Hosted Shopping Cart Works 4 Bob’s browser is returned to The Stuff Shop website, which displays a “Thank you” page. FIGURE 4.4 PayPal-Hosted Shopping Cart Example: Thank You Page After Payment Bob receives an email receipt for this transaction that confirms the payment and payment details. FIGURE 4.
4 Multiple-Item Payment: Shopping Cart Button Factory for PayPal-Hosted Shopping Cart Button Factory for PayPal-Hosted Shopping Cart With the PayPal-hosted shopping cart, customers can make a single payment for multiple items. With our shopping cart button factory, you can create a separate Add to Cart button for each item and put the automatically generated HTML code for that button on your website next to the item.
Multiple-Item Payment: Shopping Cart Button Factory for PayPal-Hosted Shopping Cart 4 1. Calculate shipping and tax. If you have specified shipping rates or tax calculations in your Profile, they are listed under Shipping Cost Calculation and Sales Tax Calculation. For more information, see “Automatic Calculation of Shipping and Handling Cost and Tax” on page 45.” 2. Add option fields to your button. Creating an option field lets your customers specify information about their purchases.
4 Multiple-Item Payment: Shopping Cart Button Factory for PayPal-Hosted Shopping Cart – Shipping Address: If you would like your customers to be prompted to provide a shipping address, choose Yes. If you choose No, your customers will not be asked to provide a shipping address. 7. Collect additional information from your customers. – Note: Select Yes if you would like your customers to be able to include a note to you with their payments.
Multiple-Item Payment: Shopping Cart Sample HTML for PayPal-Hosted Shopping Cart 4 – Paste the code you just copied into your web page file where you would like your “View Cart” button to appear, by either pressing Ctrl+V or by right-clicking your mouse and choosing Paste. Sample HTML for PayPal-Hosted Shopping Cart The following HTML is of a generic Add to Cart button created with the PayPal Shopping Cart button factory. Several optional fields are shown. EXAMPLE 4.
4 Multiple-Item Payment: Shopping Cart How A Third-Party Shopping Cart Works How A Third-Party Shopping Cart Works This example shows how PayPal can work with a third-party shopping cart and with the following features: z z Account Optional is turned off. In this example, to pay with PayPal, the customer must already have a PayPal account. For more information, see “Account Optional or Website Payments Express” on page 35.” Auto Return is enabled.
Multiple-Item Payment: Shopping Cart How A Third-Party Shopping Cart Works 4 In this example integration, the contents of the shopping cart are displayed each time an item is added to the cart. FIGURE 4.7 Third-Party Shopping Cart Example: Proceed to Checkout After selecting all the items he wants, Bob clicks Proceed to Checkout.
4 Multiple-Item Payment: Shopping Cart How A Third-Party Shopping Cart Works Bob’s browser is redirected to the PayPal website, where he enters his PayPal username and password and clicks Continue to login. FIGURE 4.
Multiple-Item Payment: Shopping Cart How A Third-Party Shopping Cart Works 4 Bob is taken to a confirmation page showing the details of his payment. FIGURE 4.9 Third-Party Shopping Cart Example: Confirmation Page Because DesignerFotos has activated Profile-based shipping preferences, the shipping costs are automatically added to the order. For information about automatic shipping calculation, see “Automatic Calculation of Shipping and Handling Cost and Tax” on page 45.
4 Multiple-Item Payment: Shopping Cart How A Third-Party Shopping Cart Works Bob’s browser is returned to the merchant’s website, which displays a “Thank you” page. FIGURE 4.10 Shopping Cart Example: Thank You Page After Payment Bob receives an email receipt for this transaction that confirms the payment and includes a copy of the payment details. FIGURE 4.
Multiple-Item Payment: Shopping Cart How A Third-Party Shopping Cart Works 4 What You See DesignerFotos receivers an receives an email notification of Bob’s payment. FIGURE 4.12 Example: Seller’s Email Receipt DesignerFotos (the user seller@designerfotos.com) can also see the payment in the PayPal account history.
4 Multiple-Item Payment: Shopping Cart Adding PayPal to Your Third-party Shopping Cart Adding PayPal to Your Third-party Shopping Cart Instead of relying on the PayPal-hosted Shopping Cart, some web developers want to integrate PayPal payment processing with their own third-party shopping cart. The details in this section allow your buyers to pay with PayPal when they are ready to check out after adding all of their items to your third-party shopping cart.
Multiple-Item Payment: Shopping Cart Adding PayPal to Your Third-party Shopping Cart 4 item_name_2, amount_2, and quantity_2; the third item with variables like item_name_3, amount_3, and quantity_3; and so on. IMPO RTANT: The _x values must increment by one continuously in order to be recognized. If you skip from item #1 to item #3 without defining an item #2, the third item will be ignored. The minimum required HTML for your post to PayPal looks similar to the following. EXAMPLE 4.
4 Multiple-Item Payment: Shopping Cart Adding PayPal to Your Third-party Shopping Cart N O T E : One drawback of this method is that your buyers will not see the individual items in their carts. In addition, you cannot change our variable names, nor can you add your own variable names. The following HTML is identical to “HTML for Passing Individual Item Detail to PayPal” on page 83 except the individual items’ amounts and item names have been aggregated into a single item and amount. EXAMPLE 4.
5 Encrypted Website Payments To add security to online payments, you can create Encrypted Website Payment (EWP) button code that relies on standard public key encryption. With public and private keys, you can dynamically encrypt payment information before sending it to PayPal. Encrypted Website Payments works in the following way. TABLE 5.
5 Encrypted Website Payments Creating Your Public Certificate Public Key Encryption Background Public key encryption (asymmetric encryption) improves security and convenience by allowing senders and receivers to have separate public and private encryption keys: z z z The public key: The public key is the portion of an asymmetric cryptographic key that receivers give senders who want to send them encrypted information.
Encrypted Website Payments Uploading Your Public Certificate 5 Uploading Your Public Certificate To upload your public certificates to the PayPal website: 1. Log in to your Business or Premier PayPal account. 2. Click the Profile subtab. 3. In the Seller Preferences column, click Encrypted Payment Settings. 4. Click Add. 5. Click Browse, and select the public certificate you want to upload. When your public certificate is successfully uploaded, it appears on the next screen under Your Public Certificates.
5 Encrypted Website Payments Removing Your Public Certificate FIGURE 5.2 Download PayPal’s Public Certificate for EWP Removing Your Public Certificate N O T E : If you remove your public certificate, it’s associated certificate ID is no longer valid for encrypting buttons, and any buttons generated by your website with that certificate ID will not function correctly. To remove one or more of your public certificates: 1. Log in to your Business or Premier PayPal account. 2. Click the Profile subtab. 3.
6 Testing in the PayPal Sandbox The PayPal Sandbox can be used to test the following functionality. IMPO RTANT: The z z z Sandbox does not process real money. Buy Now and Donations: Test single-item payments. For more information, see Chapter 3, “Single-Item Payment: Buy Now and Donations.” Shopping Carts: Test the purchase of multiple items in a single transaction and making a single payment. For more information, see Chapter 4, “Multiple-Item Payment: Shopping Cart.
6 90 Testing in the PayPal Sandbox November 2005 Website Payments Standard Checkout Integration Guide
7 Website Payments Standard HTML FORM Basics This chapter describes the basic functionality of Website Payments Standard HTML FORMs in technical terms. Your customers interface with Website Payments Standard through hidden HTML FORM input variables on your website. These FORMs submit variables and their values to PayPal. You set these variables to produce the desired effect.
7 Website Payments Standard HTML FORM Basics Specifying the Website Payments Standard Product: cmd Specifying the Website Payments Standard Product: cmd The cmd variable is always required in a FORM. Its value determines which Website Payments Standard product you are using to obtain payment from the customer: TABLE 7.
Website Payments Standard HTML FORM Basics Variations on Basic Variables z item_number or item_number_x z invoice 7 Setting the Character Set: charset You can use the charset FORM variable to specify the character set or character encoding of the data you collect in your website forms and send to PayPal. PayPal sends data to you in the same character set or encoding you specify with the charset variable.
7 Website Payments Standard HTML FORM Basics Prepopulating FORMs The value of currency_code must be a code from Table 2.2, “PayPal-Supported Currencies, Currency Codes, and Maximum Transaction Amounts” on page 56. N O T E : If currency_code is not included, the default currency is USD. URL-Encoding Variable Values Variables such as return, cancel_return, image_url require a URL as their values. You must ensure that these values are URL-encoded before you pass them to PayPal.
Website Payments Standard HTML FORM Basics Overriding PayPal-Stored Addresses 7
7 Website Payments Standard HTML FORM Basics Instant Payment Notification: notify_url
Website Payments Standard HTML FORM Basics Instant Payment Notification: notify_url 7 RefundTransaction. If the payment has a “Pending” status, you receive another IPN when the payment clears, fails, or is denied. 2. PayPal posts HTML FORM variables to a program at a URL you specify. You can specify this URL either in your Profile or with the notify_url variable on each transaction. This post is the heart of IPN.
7 98 Website Payments Standard HTML FORM Basics Instant Payment Notification: notify_url November 2005 Website Payments Standard Checkout Integration Guide
A Website Payments Standard HTML Variables This appendix details all variables for Buy Now, Donations, Add to Cart buttons and shopping carts. TABLE A.1 Allowed Values for cmd Variable Value of cmd Description _xclick A Buy Now or Donations button _cart A shopping cart _ext-enter TABLE A.2 For prepopulating PayPal account signup. Requires redirect_cmd. HTML Variables: IPN Control notify_url Name Description notify_url The URL to which PayPal posts information about the transaction.
A Website Payments Standard HTML Variables TABLE A.3 HTML Variables: Item Information Required or Optional Name Description quantity Number of items. The amount, shipping and tax are multiplied by the quantity to derive the total payment amount. If this is a shopping cart transaction, PayPal appends the number of the item (e.g. quantity1, quantity2). Character Length Optional N O T E : The value for quantity must be a positive integer. Null, zero, or negative numbers are not allowed.
Website Payments Standard HTML Variables TABLE A.4 A HTML Variables: Display Information Required or Optional Character Length Name Description cancel_ return A URL to which the customer’s browser is returned if payment is cancelled; for example, a URL on your website that displays a “Payment Canceled” page. Default: Browser is directed to the PayPal website. Optional cbt Sets the text for the Continue button on the PayPal Payment Complete page.
A Website Payments Standard HTML Variables TABLE A.4 HTML Variables: Display Information Required or Optional Character Length Name Description image_url The URL of the 150x50-pixel image displayed as your logo in the upper left corner of PayPal’s pages. Must be URL-encoded. Default: your business name (if you have a Business account) or your email address (if you have Premier account). Optional no_note Prompt customer to include a note with payment.
Website Payments Standard HTML Variables TABLE A.5 A HTML Variables: Transaction Information Name Description address_ override 1: The address specified in prepopulation variables overrides the user’s stored address. See Table A.8, “HTML Variables: Prepopulating PayPal FORMs or Address Overriding. The Required or Optional Character Length Optional 1 customer is shown the passed-in address but cannot edit it.
A Website Payments Standard HTML Variables TABLE A.5 HTML Variables: Transaction Information Required or Optional Name Description tax Transaction-based tax override variable. Set this to a flat tax amount to apply to the transaction regardless of the buyer’s location. This value overrides any tax settings set in your Profile. Default: Profile tax settings (if any) apply. Optional tax_cart Cart-wide tax, overriding any individual item tax_x value Optional TABLE A.
Website Payments Standard HTML Variables TABLE A.7 A HTML Variables: Individual Items in Third-Party Shopping Carts Name Required or Optional Description handling_x Optional The cost of handling for item #x. item_name_x Required Name of item #x in the cart. Must be alphanumeric. 127 item_number_x Optional Passthrough variable for you to track order or other purchase. Default: no variable is passed back to you.
A Website Payments Standard HTML Variables TABLE A.8 HTML Variables: Prepopulating PayPal FORMs or Address Overriding Variable Description Requirements Character Limit last_name Last name Alphabetic 64 lc Defines the buyer’s checkout flow language. Allowable values: Alphabetic 2 AU DE FR IT GB ES US night_ phone_a The area code for U.S. phone numbers, or the country code for phone numbers outside the U.S. This will prepopulate the buyer’s home phone number.
Website Payments Standard HTML Variables TABLE A.
A 108 Website Payments Standard HTML Variables November 2005 Website Payments Standard Checkout Integration Guide
B Country Codes ISO 3166 Standard Country Codes PayPal relies on two-character country codes defined by International Standards Organization (ISO) 3166. TABLE B.
TABLE B.
TABLE B.
November 2005
Index Index Symbols .NET SDK Guide 26 _cart 75, 82, 83, 84, 92, 99 _ext-enter 94, 99, 103 _xclick 65, 92, 94, 95, 99, 103 A Account Information 28 Account Optional 35, 94 customer experience 36 account profile summary see "Profile".
Index D for aggregated shopping cart 84 for Buy Now button 65 shopping cart with individual items 83 https 62 DesignerFotos 16 Developer Central 89 Direct Payment API 24 display 67, 101 Donations 23 Downloadable History Log 22 I E eChecks 49 email 105 email notification 21 disabling 21 Encrypted Website Payments 62, 64, 85 EWP. See "Encrypted Website Payments.
Index O public certificate 86 on0 75, 100 on0_x 105 on1 100 on1_x 105 OpenSSL 86 Order Management Integration Guide 22, 24, 25 os0 75, 100 os0_x 105 os1 100 os1_x 105 overriding page styles 33 PayPal-stored shipping address 95, 103 return URL on individual transactions 45, 93 shipping calculations on individual transactions 47, 103 tax calculations on individual transactions 46 P page_style 32, 33, 102 partial refund 58 passthrough variables, defined 92 Pay Anyone 48 Payment Data Transfer 24 Payment Rec
Index T Y tax 104 tax. See "sales tax.
