Merchant User Manual and Integration Guide Last Updated: May, 2005
Merchant User Manual and Integration Guide © 2005 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.
© 2005 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.
May, 2005 Merchant User Manual and Integration Guide
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 19 PayPal-Supported Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Chapter 2 PayPal Payments Overview . . . . . . . . . . . . . . . . . 21 PayPal Account Optional . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Your Customer’s Experience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 What Your Customer Sees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Chapter 5 Creating Buy Now and Donation Buttons . . . . . . . . . . 43 How Buy Now and Donations Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 What Your Customer Sees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 What You See . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Examples of Custom Payment Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Adding a Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Editing a Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Previewing a Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents How It Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Enabling Payment Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Setting Up Payment Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . .101 Instant Payment Notification (IPN) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103 How It Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103 How IPNs Are Sent . . . . . . . . . .
Contents Notification Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127 Button Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127 Multi-User Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128 Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129 Using Secure Socket Layer (SSL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Dispute Notification Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160 PDT-Specific Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162 Appendix C Country Codes . . . . . . . . . . . . . . . . . . . . . . 163 ISO 3166 Standard Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
List of Tables Table 1.1 PayPal-Supported Currencies, Currency Codes, and Maximum Transation Amounts 20 Table 1.2 Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Table 8.1 Order of Customization Variables . . . . . . . . . . . . . . . . . . . . . 80 Table 14.1 Character Sets and Encodings Supported by PayPal . . . . . . . . . . .120 Table A.1 HTML and Hyperlink Variables for Buy Now and Donations Buttons. . . .133 Table A.2 Shopping Cart Variables . . . . . . . .
List of Tables 12 May, 2005 Merchant User Manual and Integration Guide
List of Figures Figure 2.1 PayPal Payment Flows Figure 3.1 Business Account Sign-up . . . . . . . . . . . . . . . . . . 27 Figure 3.2 Confirming Your Email Address Figure 3.3 Adding a Bank Account . . . . . . . . . . . . . . . . . . . 28 Figure 3.4 Merchant Profile Page . . . . . . . . . . . . . . . . . . . . 30 Figure 3.5 Payment Receiving Preferences . . . . . . . . . . . . . . . 31 Figure 8.1 Payment Page in Standard PayPal Page Style . . . . . . . . . 73 Figure 8.
List of Figures 14 May, 2005 Merchant User Manual and Integration Guide
Preface This Document This document, the Merchant User Manual and Integration Guide, which describes how to use and integrate PayPal features for merchants, replaces the PayPal Merchant User Manual and Integration Guide, issued in February, 2005. Intended Audience This document is written for merchants whose websites use PayPal features to obtain payments from PayPal members. Notational Conventions This document uses typefaces to identify the characteristics of text.
Preface Typeface How Used San-serif oblique Placeholders used in the context of a format or programming standard or formal descriptions of PayPal system syntax. Placeholders indicate values or names that the reader should provide. Example: For example, amount is the variable for a single-item shopping cart, but amount_X is the name of the variable for a multi-item shopping cart. amount_3 is the item amount for the third item in a multiple-item shopping cart.
Preface Merchant User Manual and Integration Guide May, 2005 17
Preface 18 May, 2005 Merchant User Manual and Integration Guide
1 Introduction The Merchant User Manual and Integration Guide provides information about the majority of PayPal's features, and instructions for using these features to meet your online payment needs. Use the Merchant User Manual and Integration Guide to: z z z Quickly and easily set up eCommerce functionality with PayPal. For example, learn how to integrate PayPal into your website in minutes with the PayPal Shopping Cart or Buy Now buttons.
1 Introduction PayPal-Supported Currencies PayPal-Supported Currencies The following currencies are supported by PayPal. TABLE 1.1 PayPal-Supported Currencies, Currency Codes, and Maximum Transation Amounts Code Currency Maximum Transaction Amount AUD Australian Dollar 12,500 AUD CAD Canadian Dollar 12,500 CAD EUR Euro 8,000 EUR GBP Pound Sterling 5,500 GBP JPY Japanese Yen 1,000,000 JPY USD U.S.
2 PayPal Payments Overview This section provides a brief overview of each of the products described in this manual. PayPal Account Optional With PayPal Account Optional turned on, your customers who are new to PayPal will be able to make credit card payments without signing up for a PayPal account. This setting is available from your Profile, and is available to Premier and Business accounts. PayPal Account Optional is turned on by default for all U.S. Premier and Business accounts.
2 PayPal Payments Overview Shopping Cart Benefits of Buy Now and Donations Buttons include: z z z z Easy to implement — no CGI scripting necessary. No up-front costs — you’ll have the same low fee schedule used as when you receive other PayPal payments. Sell with ease — PayPal maintains detailed transaction records on the PayPal website. Improve buyer experience — with customizable buttons and secure payments, happy customers become repeat customers.
PayPal Payments Overview Contact Telephone Number 2 For more information about shipping and tax, see Chapter 9, “Calculating Shipping, Handling, and Tax.” Contact Telephone Number The Customer Contact Information Telephone field provides merchants with a contact telephone number for their buyer. In accordance with our User Agreement, merchants may only use this Contact Telephone Number to communicate with buyers about the related purchase. This number may not be used for unsolicited commercial messages.
2 PayPal Payments Overview Payment Receiving Preferences For more information about IPN, “Instant Payment Notification (IPN) ” on page 103. Payment Data Transfer Payment Data Transfer (PDT) provides merchants with the ability to display transaction details to buyers who are redirected back to their site upon payment completion. For more information about PDT, see “Payment Data Transfer” on page 96.
PayPal Payments Overview Subscriptions 2 For more information about PayPal's Reporting Tools, see https://www.paypal.com/us/cgibin/webscr?cmd=p/xcl/rec/reports-intro-outside. Subscriptions PayPal Subscriptions and Recurring Payments is a service that will let you accept recurring payments for your service. When you set up Subscriptions, you can offer your subscribers a trial period, special introductory rates, and a regular rate.
2 PayPal Payments Overview Payment Flow Overview Payment Flow Overview The following diagram represents an overview of the PayPal payment flows. FIGURE 2.
3 Getting Started You can start accepting payments with PayPal in 5 easy steps: Step 1 - Sign Up: Go to https://www.paypal.com/ and click the Sign Up link in the upper righthand corner of the page. Click the Business link to sign up for a Business account, as shown in the following diagram. Make sure to write down the email address you use and the password you choose; in the future, you will use them to login to your PayPal account. FIGURE 3.
3 Getting Started FIGURE 3.2 Confirming Your Email Address Step 3 - Add Bank Account: In order for PayPal to add funds to your bank account, you must add it. Before you add your bank account, you will need a check or deposit slip for that bank account. Log in to your PayPal account and click the Profile subtab of the My Account tab. Click the Bank Accounts link in the Financial Information column. On the Bank Accounts page, click Add to reach the page shown in the following diagram.
Getting Started Managing Your PayPal Merchant Account 3 credit card used on your PayPal account. If you decide to add additional credit cards to your PayPal account, you can select any of them as your primary card. In addition, the credit card billing address you entered when you added your credit card is now a Confirmed Address. Many sellers require that buyers use their Confirmed Address as their shipping address when they pay with PayPal.
3 Getting Started Managing Your PayPal Merchant Account FIGURE 3.4 Merchant Profile Page Account Information Use the Account Information column to perform basic account maintenance, including updating your password, adding and confirming email addresses, and managing your business information.
Getting Started Managing Your PayPal Merchant Account 3 Payment Receiving Preferences Once you have set up your PayPal account, you’re ready to start receiving payments. Your Payment Receiving Preferences let you manage the types of payments you receive, including: z Block payments from U.S. users that do not have a confirmed address. z Block payments sent to you in a currency you do not hold. z Block payments from users with non-U.S. PayPal accounts.
3 Getting Started Managing Your PayPal Merchant Account Addresses to help you make informed decisions when shipping goods. To be eligible for PayPal's Seller Protection Policy, and to help reduce your risk of dealing with fraudulent buyers, ship to a buyer’s Confirmed Address. There are three choices for this preference: z z z Yes: All payments from U.S. buyers without a Confirmed Address will be blocked. All U.S. buyers will be required to provide a Confirmed Address in order to pay you.
Getting Started Managing Your PayPal Merchant Account 3 Smart Logos, or eBay Checkout Payments. Selecting this option may help you manage your account, because all of the PayPal payments you receive will be attached to a specific item or transaction that you previously defined. If you choose not to block these payments, you will accept all payments, including those initiated via the Pay Anyone subtab of the Send Money tab.
3 34 Getting Started Managing Your PayPal Merchant Account May, 2005 Merchant User Manual and Integration Guide
4 PayPal Account Optional With PayPal Account Optional turned on, your customers who are new to PayPal will be able to make credit card payments without signing up for a PayPal account. This setting is available from your Profile for Premier and Business accounts. PayPal Account Optional is turned on by default for all U.S. Premier and Business accounts.
4 PayPal Account Optional Your Customer’s Experience Your Customer’s Experience If you have turned PayPal Account Optional off, the checkout experience for a customer who doesn’t currently have a PayPal account is the same as in the past: the customer is required to sign up for a PayPal account to complete the payment and then returned to your website.
PayPal Account Optional Your Customer’s Experience 4 Step 3: Bob is prompted to enter the shipping information for his purchase, and to let Alice know if the shipping address he has entered is the same as the billing address on his credit card. If it is, he clicks Yes.
4 PayPal Account Optional Your Customer’s Experience Step 4: Bob is then prompted to fill in his billing information for the credit card he wishes to use for the purchase. The purchase will be shipped to the shipping address he has provided.
PayPal Account Optional Your Customer’s Experience 4 Step 5: Bob is taken to a Review page containing the details of his purchase. Because Alice has activated Profile-based Shipping for all of her transactions, the Shipping amount for this purchase ($2.00) is automatically added to Bob’s purchase. He clicks Complete Checkout to complete his purchase. N O T E : For more information about setting Shipping preferences, see Chapter 9, “Calculating Shipping, Handling, and Tax.
4 PayPal Account Optional Your Customer’s Experience Step 6: Bob is taken to a payment completion page where he sees his Receipt ID for this transaction, and Alice's customer service contact information. He can use both to contact Alice with any questions about his purchase. If Bob clicks Save My Info, he will be taken to a page where he can enter the rest of the information needed to create a PayPal account (see Step 7).
PayPal Account Optional Your Customer’s Experience 4 Step 7: If Bob clicked Save My Info, he is taken to a page where he can complete signup 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. If he clicks Continue, he will be redirected to either Alice’s site or to PayPal, depending on how she has set her return preferences for the button.
4 PayPal Account Optional Your Customer’s Experience Step 9: Bob receives an email receipt for this transaction, confirming his payment and including a copy of his Payment details.
5 Creating Buy Now and Donation Buttons PayPal makes it easy to accept payments for single items through your own website. The Buy Now and Donations Buttons features can be implemented in minutes, giving you easy access to business and donors from PayPal’s millions of members, and any other buyer on the Web. Because using Buy Now and Donations Buttons to send and receive payments is secure, both you and your customers remain protected.
5 Creating Buy Now and Donation Buttons How Buy Now and Donations Work What Your Customer Sees Step 1: Bob goes to Alice’s website and clicks Buy Now or Donations. Step 2: Bob is taken to a PayPal Payment Details page which shows the details of the payment he is about to make. Step 3: Bob is prompted to log in to his PayPal account; however, he is not already a PayPal member, so he clicks If you have never paid through PayPal, Click Here, as shown in the following picture.
Creating Buy Now and Donation Buttons How Buy Now and Donations Work 5 Step 4: To pay for his purchase or donation, Bob is prompted to add a credit card, email address, and password, which creates his new PayPal account.
5 Creating Buy Now and Donation Buttons How Buy Now and Donations Work Step 5: Bob is taken to a Payment Details page that contains the details of his purchase or donation. Bob clicks Pay to complete his purchase or donation, as shown in the following diagram. For donations, Bob would choose a shipping address before clicking Pay so Alice can send him a tax receipt. The Shipping amount for this purchase, $2.
Creating Buy Now and Donation Buttons How Buy Now and Donations Work 5 Step 6: Bob is taken to a payment completion page where he sees the details of his transaction. He is also given Alice’s customer service email address. He clicks the Continue link and is returned to a page on Alice’s website, which she specified when she created her payment or donation button. With Auto Return for Website Payments, Bob is redirected back to Alice's site immediately after clicking Pay on the Payment Confirmation page.
5 Creating Buy Now and Donation Buttons How Buy Now and Donations Work Step 7: Bob receives an email receipt for this transaction, confirming his payment and including a copy of his payment details. What You See Step 8: Alice receives an email notification of Bob’s payment.
Creating Buy Now and Donation Buttons Buy Now and Donations Button Factory 5 Step 9: Alice logs in to her PayPal account to check the payment or donation Bob has sent. Step 10: The funds from Bob’s payment are now reflected in Alice’s PayPal account balance. She ships the book to Bob, or sends him a tax receipt for a donation. N O T E : For more information about PayPal’s fees, please click the Fees link at the bottom of any PayPal Web page, or visit https://www.paypal.com/fees.
5 Creating Buy Now and Donation Buttons Buy Now and Donations Button Factory Creating a Buy Now Button Step 1: Enter the details for your item (all fields are optional): – Item Name/Service: Enter the name of the item or service you wish to sell. If you do not enter anything in this field, your customers will be able to complete it at the time of purchase. PayPal recommends entering an Item Name to make it easier for you to ship the order.
Creating Buy Now and Donation Buttons Buy Now and Donations Button Factory 5 Step 4: Shipping and Sales Tax – Shipping Cost Calculation: If you have already specified shipping rates in your Profile, they will be listed here. To learn more about charging for shipping, see Chapter 9, “Calculating Shipping, Handling, and Tax.” – Sales or Value Added Tax Calculation: If you have already specified your tax rate from your Profile, it will be listed here.
5 Creating Buy Now and Donation Buttons Buy Now and Donations Button Factory Step 8: Miscellaneous Options – Quantity: If you would like to let your customers purchase more than one of your item or service, choose Yes. They will then be prompted to enter the quantity of the item they want to buy. If you choose No, the quantity will be set to 1 and your customers will only be able to purchase one item per payment.
Creating Buy Now and Donation Buttons Buy Now and Donations Button Factory 5 If you will be sending your customers the payment link via email: Copy the code from the For Emails text box by highlighting all of the text and pressing Ctrl+C, or by highlighting all of the text, right-clicking on your mouse, and choosing Copy. Open the email you wish to send. Paste the code you just copied into your email by either pressing Ctrl+V or by right-clicking on your mouse and selecting the Paste option.
5 Creating Buy Now and Donation Buttons Buy Now and Donations Button Factory Step 4: Customize Your Donors’ Experience – Successful Payment URL: Enter the URL where you would like to send your donors after they have completed payment. Once your donor has completed his payment, he will see a payment confirmation page. From this page, he will click Click to Continue and return to the successful payment URL you have specified.
Creating Buy Now and Donation Buttons Buy Now and Donations Button Factory 5 1. Copy the code from the For Emails text box by highlighting all of the text and pressing Ctrl+C, or by highlighting all of the text, right-clicking on your mouse, and selecting Copy. 2. Open the email you wish to send. 3. Paste the code you just copied into your email by either pressing Ctrl+V, or right-clicking on your mouse and selecting Paste. When your donors receive the email, the code will appear as a link.
5 Creating Buy Now and Donation Buttons Notifications You Receive Notifications You Receive You can be notified of payments in these three ways: email, history transaction log, and downloadable history transaction log. You can be notified of payments in these four ways: email, history transaction log, downloadable history transaction log, and (if you have activated it) Instant Payment Notification (IPN).
Creating Buy Now and Donation Buttons Notifications You Receive 5 Instant Payment Notification (IPN) If you have Instant Payment Notification activated, you will receive an IPN when a payment is first sent, which will state the status of the payment (Completed or Pending). If the payment was Pending, you will receive another IPN when the payment clears, fails, or is denied. To learn more about IPN, see “Instant Payment Notification (IPN) ” on page 103.
5 58 Creating Buy Now and Donation Buttons Notifications You Receive May, 2005 Merchant User Manual and Integration Guide
6 Creating Shopping Cart Buttons When you use PayPal’s free Shopping Cart, your customers can purchase multiple items with a single payment, browse your entire selection, and view a consolidated list of all their items before purchasing. The PayPal Shopping Cart is a low-cost way for you to accept credit card and bank account payments, and can be fully integrated with your website in a few easy steps.
6 Creating Shopping Cart Buttons How It Works Step 2: Bob looks at the contents of his cart and clicks Checkout. Step 3: Bob is taken to a PayPal Payment Details page which shows the items he has added to his Cart. Step 4: Bob is prompted to log in to his PayPal account, but he is not already a PayPal member, so he follows the instructions at the top of the screen.
Creating Shopping Cart Buttons How It Works 6 Step 5: Bob is then prompted to enter his credit card information, email address, and password, creating his new PayPal account. N O T E : Existing PayPal users log in to their accounts directly and skip Step 5.
6 Creating Shopping Cart Buttons How It Works Step 6: Bob is taken to a Confirmation page containing the details of his payment. Because Alice has activated her Shipping Preferences, the shipping costs are automatically added to Bob’s order. He clicks Pay to complete the payment.
Creating Shopping Cart Buttons How It Works 6 Step 7: Bob is taken to a Confirmation page where he sees the details of his successful payment. He is also given Alice’s customer service email. With Auto Return for Website Payments, Bob would be redirected back to your site immediately after clicking the Pay button on the Payment Confirmation page. To learn more about Auto Return, see Chapter 11, “Auto Return.
6 Creating Shopping Cart Buttons PayPal Shopping Cart Button Factory What You See Step 9: Alice receives an email notification of Bob’s payment. Step 10: Alice logs into her PayPal account to check the payment Bob has sent. Step 11: The funds from Bob’s payment are now reflected in Alice’s PayPal account balance. She ships the books to her satisfied customer. PayPal Shopping Cart Button Factory With the PayPal Shopping Cart, your buyers can make a single payment when they purchase multiple items.
Creating Shopping Cart Buttons PayPal Shopping Cart Button Factory 6 N O T E : You also have the option of prepopulating your customer’s signup information during the checkout flow. For more information, and a list of variables, see “Prepopulating Your Customer’s PayPal Sign-Up ” on page 141. Getting Started 1. Log in to your PayPal account at https://www.paypal.com. 2. Click the Merchant Tools tab. 3. Select the PayPal Shopping Cart link under the Website Payments heading to get to the Button Factory.
6 Creating Shopping Cart Buttons PayPal Shopping Cart Button Factory If you have already specified your tax rate from your Profile, it will be listed under Sales Tax Calculation. For more information about calculating tax, see Chapter 9, “Calculating Shipping, Handling, and Tax.” Step 4: Add option fields to your button. Let your customers specify information about their purchases by creating an option field. You can use option fields to specify information such as color, size, or gift wrapping.
Creating Shopping Cart Buttons PayPal Shopping Cart Button Factory 6 Step 9: 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 payment. If you select No, your customers will not be given the opportunity to include a note. – Note Title: If you are allowing your customers to include a note with their payment, you may choose a title for the note field.
6 Creating Shopping Cart Buttons How You Get Your Money 1. Copy the code from the Copy ‘View Cart’ button HTML box by highlighting all of the text and pressing Ctrl+C, or by highlighting all of the text, right-clicking on your mouse, and choosing Copy. 2. Open each Web page from which you would like your customers to be able to get to their PayPal Shopping Carts. 3.
Creating Shopping Cart Buttons Notifications You Receive 6 2. Click the Notifications link from the left-hand menu. 3. Find the Payment Notifications heading and clear the I receive PayPal Website Payments and Instant Purchase checkbox. 4. Click Save. History Your transaction history log (“History”) contains information about your payments. Each payment has one of the following statuses: z z z Completed: The transaction was successful and the money was credited to your account.
6 70 Creating Shopping Cart Buttons Notifications You Receive May, 2005 Merchant User Manual and Integration Guide
7 Adding PayPal to Your Thirdparty Shopping Cart Some Web developers may wish to integrate PayPal payment processing with their own thirdparty shopping cart instead of the standard PayPal Shopping Cart. Please use the following instructions and variables to 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. There are now two ways to integrate your third-party shopping cart with the PayPal payment flow.
7 Adding PayPal to Your Third-party Shopping Cart Passing the Aggregate Shopping Cart Amount to PayPal 3. Add a new variable called upload by adding the following line between the
tags: 4. Define item details. For each of the following item-specific parameters, define a new set of values that correspond to each item that was purchased via your third-party cart.8 Custom Payment Pages With our Custom Payment Pages feature, you can tailor PayPal's payment pages to the style of your website for a truly seamless payment experience. Make PayPal's payment flow yours with custom page colors and your own images. Custom Payment Pages can be used with all PayPal Website Payment buttons, including Buy Now, Donations, Shopping Cart, and Subscriptions.
8 Custom Payment Pages Examples of Custom Payment Pages Figure 8.2, “Payment Page with Custom Style: Header Image and Header Border,” shows a custom header image and header border color. FIGURE 8.
Custom Payment Pages Getting Started 8 Figure 8.3, “Payment Page with Custom Style: Header Image, Image Border, and Background Color,” shows a custom header image, header border color, and page background color. FIGURE 8.3 Payment Page with Custom Style: Header Image, Image Border, and Background Color Getting Started 1. Log in to your PayPal account at https://www.paypal.com 2. Click the Profile sub-tab. 3.
8 Custom Payment Pages Adding a Page Style Adding a Page Style You can add up to three page styles. To add a page style: 1. Begin at the Custom Payment Page Styles page. 2. Click Add. 3. Enter your page style preferences:. – Page Style Name (required) Enter a name up to 30 characters in length. The name can contain letters, numbers, and the underscore mark - but no other symbols or spaces.
Custom Payment Pages Editing a Page Style 8 Editing a Page Style To edit a page style: FIGURE 8.4 Editing Page Style Settings 1. Begin at the Custom Payment Page Styles page. For more information, see “Getting Started” on page 75. 2. Click the radio button next to the page style you wish to edit. 3. Click Edit.
8 Custom Payment Pages Previewing a Page Style 4. Keep or modify your page style preferences: – Page Style Name (required) Enter a name up to 30 characters in length. The name can contain letters, numbers, and the underscore mark - but no other symbols or spaces. The Page Style Name will be used to refer to the page style within your PayPal account and in the HTML code for your PayPal Website Payment buttons.
Custom Payment Pages Making a Page Style Primary 8 Making a Page Style Primary When you make a page style Primary, it is applied to all of your payment pages unless you specify otherwise. To learn how to apply a page style other than your Primary style, Chapter 8, “Custom Payment Pages.” N O T E : If you do not designate page style as Primary, the default PayPal page style is used. To make a page style Primary: 1. Begin at the Custom Payment Page Styles page.
8 Custom Payment Pages Overriding Page Style Settings To change the page style for a button you have already created, you can modify the button's HTML code, replacing the value of the page_style variable with the Page Style Name of the style you wish to apply. The next time the button is clicked, its payment pages will appear in the new style.
Custom Payment Pages Background Colors and Error Messages 8 Background Colors and Error Messages PayPal’s error message system highlights errors in red. PayPal does not allow certain background colors that make these error messages unreadable. The background color of the following payment page is not allowed. The color makes the fields the customer must complete difficult to read. FIGURE 8.
8 Custom Payment Pages Background Colors and Error Messages The background color of the following payment page is allowed. Unlike in the previous example, the fields displayed in red are easy to read. FIGURE 8.6 Example of Allowable Background Color To verify that your background color is allowed, enter its hex code into the Background Color field on the Custom Payment Pages page under the Profile subtab of the My Account tab and click Preview.
9 Calculating Shipping, Handling, and Tax You can set up your PayPal account to automatically calculate and charge shipping and sales tax (also called “value added tax”). Getting Started To view or modify your sales tax and shipping charges: 1. Log in to your PayPal account at https:www.paypal.com. 2. Click the Profile subtab of the My Account tab. 3. Click the Sales Tax or the Shipping Calculation link in the Selling Preferences column.
9 Calculating Shipping, Handling, and Tax Shipping Calculation Shipping Calculation Determine whether you would like to charge your customers for shipping as a flat amount or a percentage of the total purchase amount. Flat Amount A flat amount is charged based on the subtotal of a purchase. Here’s an example. EXAMPLE 9.1 Flat Amount Shipping Calculation Your flat amount settings are: $0.00 through $49.99 = $3.00 $50.00+ = $6.00 – If your customer’s subtotal is $36.50, your customer is charged $3.
Calculating Shipping, Handling, and Tax Shipping Calculation 9 handling_cart variables. For more information and a complete list of the Buy Now button variables, see “Sample Buy Now Button HTML” on page 131. To make sure that the shipping HTML in your Shopping Cart Button overrides your Profile Shipping Calculation settings: 1. Go to the Shipping Calculations page in your Profile. 2.
9 86 Calculating Shipping, Handling, and Tax Shipping Calculation May, 2005 Merchant User Manual and Integration Guide
10 Creating Customer Contact Telephone The Customer Contact Information Telephone is an option that provides you with a contact telephone number for your buyer. When you activate this option, your customers are asked to include a Contact Telephone Number with their payment information. PayPal will share this number with you. In accordance with our User Agreement, you may use this Contact Telephone Number only to communicate with the buyer about the related purchase.
10 Creating Customer Contact Telephone Getting Started What Your Customer Sees Step 3: When you require the buyer’s contact telephone number, your buyer will see the information below: Getting Started Use the following instructions to activate the Customer Contact Information Telephone option: 1. Log in to your PayPal account at https://www.paypal.com. 2. Click the My Account tab. 3. Click the Profile link. 4. Click the Website Payment Preferences link. 5.
11 Auto Return With Auto Return for Website Payments, merchants can eliminate the “Done” page in the Website Payments flow and automatically return or redirect buyers to their site upon payment completion. By decreasing the Website Payments purchasing process by 1/3 and automatically bringing buyers back to their site, merchants provide their buyers with a quicker, more seamless, and continuous purchasing experience.
11 Auto Return How Auto Return Works Step 2: Bob is taken to a PayPal Payment Details page which displays the details of the payment he is about to make. Step 3: Bob enters his PayPal account information into the PayPal Login fields. (These pages are not included in this example.) N O T E : At this point, buyers that do not already have a PayPal account click the If you have never paid through PayPal, Click Here button.
Auto Return How Auto Return Works 11 Step 4: Bob is then taken to a confirmation page that displays the details of his selection, information about how his automatic payments will be funded, and his shipping information. He clicks Pay to complete payment. Step 5: A payment confirmation page appears that informs Bob that his payment has been completed and that he is being automatically redirected back to the Widget Warehouse site.
11 Auto Return How Auto Return Works Step 6: The Widget Warehouse’s “Thank You” page appears, again informing Bob that his transaction is complete and that a receipt for the purchase has been emailed to him. The page also displays a link to PayPal that Bob can use to view details of the transaction if necessary, as well as links that he can use to continue shopping.
Auto Return Setting Up Auto Return 11 Setting Up Auto Return To set up Auto Return: 1. Log in to your PayPal account at https://www.paypal.com. 2. Click the Profile subtab. 3. Click the Website Payment Preferences link under the Selling Preferences column on the right. 4. Under Auto Return for Website Payments, click the On radio button to enable Auto Return.
11 Auto Return Subscription Password Management and Auto Return 5. Enter the Return URL to which you want your buyers redirected upon payment completion in the Return URL field. You Return URL must meet the following requirements: – Per the user agreement, you must provide content on the page displayed by the Return URL that helps the buyer understand that the payment has been made and that the transaction has been completed.
12 Backend Integration - Payment Notifications PayPal offers two payment notification methods for backend integration: PayPal offers four payment notification methods for backend integration: z Emails z Reports z Instant Payment Notification (IPN) z Payment Data Transfer (PDT) Emails You will receive an email notification in the following cases: z Successful Payment z Pending Payment z Cancelled Payment If you do not want to receive payment notifications via email: 1.
12 Backend Integration - Payment Notifications Payment Data Transfer z z History Log: View an online record of your received and sent payments. Downloadable Logs: Keep track of your transaction history by downloading it into various file formats (suitable for financial settlements). For more information about PayPal's reports, see http://www.paypal.com/cgibin/webscr?cmd=p/xcl/rec/reports-intro-outside.
Backend Integration - Payment Notifications Payment Data Transfer 12 How It Works Bob is going to purchase a widget from the Widget Warehouse. Step 1: Bob goes to the Widget Warehouse website, finds the widget he wants, and clicks Buy Now. Step 2: Bob is taken to a PayPal Payment Details page which displays the details of the payment he is about to make. Step 3: Bob enters his PayPal account information into the PayPal Login fields.
12 Backend Integration - Payment Notifications Payment Data Transfer Step 4: Bob is then taken to a confirmation page that displays the details of his selection, information about how his automatic payments will be funded, and his shipping information. He clicks Pay to complete the payment. Step 5: A payment confirmation page appears that informs Bob that his payment has been completed and that he is being redirected back to the Widget Warehouse website.
Backend Integration - Payment Notifications Payment Data Transfer 12 Step 7: The Widget Warehouse's Thank You page appears and displays the transaction information, again informing Bob that his transaction has been completed and a receipt for the purchase has been emailed to him. The page also displays payment details, a link to PayPal that Bob can use to view more transaction details if necessary, as well as links that he can use to continue shopping.
12 Backend Integration - Payment Notifications Payment Data Transfer 3. Click the Website Payment Preferences link, as shown in the following diagram. The Website Payment Preferences page opens. 4. Click the Payment Data Transfer On radio button, as shown in the following diagram. N O T E : You must enable Auto Return in order to use Payment Data Transfer. Auto Return can also be enabled from the Website Payment Preferences page. 5. Click Save.
Backend Integration - Payment Notifications Payment Data Transfer 12 PDT and PayPal Account Optional Feature The PayPal Account Optional no longer requires your customers who are new to PayPal to create a PayPal account to complete a purchase—they will go through an alternate checkout, and will have the option to sign up afterward.
12 Backend Integration - Payment Notifications Payment Data Transfer custom=For+the+purchase+of+the+rare+book+Green+Eggs+%26+Ham ... If the response is FAIL, PayPal recommends making sure that the: z Transaction token is not bad. z ID token is not bad. z Token, or tokens, has not expired.
Backend Integration - Payment Notifications Instant Payment Notification (IPN) 12 Instant Payment Notification (IPN) PayPal’s Instant Payment Notification (IPN) allows you to integrate PayPal payments with your website’s back-end operations. IPN provides immediate notification and confirmation of PayPal payments you receive, allowing you to: z Customize your website’s response to customer purchases in real-time. z Track customers through the notification’s “pass through” variables.
12 Backend Integration - Payment Notifications Instant Payment Notification (IPN) How IPNs Are Sent Step 1: Your buyer comes to your website and clicks on a PayPal Buy Now button to make a purchase. Step 2: After your buyer checks the payment details and sends the payment, he will see a confirmation page, as shown in the following diagram. Step 3: At the time the payment is made, PayPal will post a notification to your server at the URL you specified.
Backend Integration - Payment Notifications Instant Payment Notification (IPN) 12 so you can be sure the IPN came from PayPal. Upon verification, PayPal will send your server a “VERIFIED” or “INVALID” response. Step 5: When you receive a VERIFIED response, you need to perform several checks before fulfilling the order. NOTE: z z z z An INVALID response could be due to inaccurate or incomplete IPN data being posted back to PayPal.
12 Backend Integration - Payment Notifications Instant Payment Notification (IPN) Setting Up IPN To set up IPN: 1. Log in to your Business or Premier PayPal account. 2. Click the Profile subtab. 3. Click the Instant Payment Notification Preferences link in the Selling Preferences column. 4. Click Edit. 5. Click the checkbox and enter the URL at which you would like to receive your IPN Notifications. 6. Click Save. Alternatively, you can activate IPN by including the notify_url field in your PayPal button.
Backend Integration - Payment Notifications Instant Payment Notification (IPN) 12 1. Check that the payment_status is Completed. 2. If the payment_status is Completed, check the txn_id against the previous PayPal transaction you have processed to ensure it is not a duplicate. 3. After you have checked the payment_status and txn_id, make sure the receiver_email is an email address registered in your PayPal account. 4.
12 Backend Integration - Payment Notifications Processing Refunds These values are absent for non-USD payments so that IPN scripts will not process these amounts as USD. However, legacy IPN scripts will continue to work as before as long as the merchant only receives USD payments. For more information about IPN multi-currency variables, see “Currency and Currency Exchange” on page 152. Dispute Notification Buyers can register claims about payments; such claims are called cases.
Backend Integration - Payment Notifications Processing Refunds 12 1. Log in to your PayPal account. 2. Click the Send Money tab. 3. Enter the required information. 4. Click Continue. 5. Review the information on the confirmation page and click Send Money to complete your transaction. N O T E : Fees assessed by Business or Premier Account receiving payments can only be reimbursed if the refund link on the Transaction Details page is used.
12 110 Backend Integration - Payment Notifications Processing Refunds May, 2005 Merchant User Manual and Integration Guide
13 Using Multiple Currencies PayPal’s Multiple Currencies feature gives you the ability to buy and sell globally. Use your current PayPal account to make or accept payments in U.S. Dollars, Canadian Dollars, Euros, Pounds Sterling, and Yen. Buyers: z Pay for purchases in your selected currency. z Payment is automatically converted to your desired currency. z No need to hold a balance in another currency to send a payment. Sellers: Accept payments directly in your selected currency.
13 Using Multiple Currencies Receiving Money currency you do not hold, you will be asked to Accept or Deny the payment as shown in the following diagram: z Accept the payment and open a new currency balance. z Accept the payment and convert it to your primary currency. z Block the payment. You can also set up your Payment Receiving Preferences to indicate how you would like to handle incoming currency payments. Receiving fees are assessed in the currency in which the funds were sent.
Using Multiple Currencies Receiving Money 13 Managing Currency Balances To manage your currency balances, please go to the Currency Balances section of your Profile, where you can: 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 will be transferred at a competitive exchange rate. To learn more about managing currency balances, see the Multiple Currencies FAQs in our Help Center.
13 114 Using Multiple Currencies Receiving Money May, 2005 Merchant User Manual and Integration Guide
14 Language Encoding for Your Data This chapter tells you how you can set your Profile preferences to indicate the language and character encoding that your website uses. Background Information Websites that use PayPal in different parts of the world work with different languages. Human languages are represented in computing by the terms character set and character encoding. A character set is a computer representation of all the individual possible letterforms or word symbols of a language.
14 Language Encoding for Your Data Changing Your Language Encoding Navigating Your Profile: Language Encoding To see or change the default language encoding for your PayPal Business account, log in to your account and click the Profile tab. click Language Encoding at the bottom Selling Preferences column, as shown in the following diagram. FIGURE 14.
Language Encoding for Your Data Changing Your Language Encoding 14 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 14.
14 Language Encoding for Your Data Changing Your Language Encoding To change the language of data PayPal should expect from your website, click the Your website’s language drop-down menu and select a different language, as shown in the illustration Figure 14.3, “Website Language Preference.” FIGURE 14.3Website Language Preference Click Save to save your selection or Cancel to to leave the setting unchanged.
Language Encoding for Your Data Changing Your Language Encoding 14 More Encoding Options If you know and 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 “More Language Encoding Options” on page 119. The More Encoding Options page allows you to specify the character encoding should expect from your website and the encoding of data PayPal sends to your website. FIGURE 14.
14 Language Encoding for Your Data Setting Language in Website Payments: charset different encoding, click the No, use radio button and select the desired encoding from the associated drop-down menu. TABLE 14.
15 Testing Website Payments, PDT, and IPN The PayPal Sandbox can be used to test the following functionality. IMPO RTANT: The z z z z z Sandbox does not process real money. Web Payments: Use the Sandbox to test accepting PayPal as a payment mechanism on a website. For more information, see the PayPal website and online help center. Shopping Cart Purchases: Use the Sandbox for testing the purchase of multiple items in a single transaction and making a single payment.
15 Testing Your PayPal Button Your PayPal Button Now that you have the HTML code in your website or in your email, you should test it. Click the link in the email or click the button on your Web page. A PayPal-hosted payment page should appear with payment details you specified. Because your PayPal user information is saved in a cookie on your computer, you will see your own PayPal username. Your customers will not see your username.
Testing Your PayPal Button 15 Testing Tips You might find the following testing tips useful when testing your buttons. Testing Tip 1 PayPal recommends starting with one of PayPal’s code samples available at https://www.paypal.com/ipn under the Code Samples section. There are code samples for the following development environments.
15 124 Testing Your PayPal Button May, 2005 Merchant User Manual and Integration Guide
16 Processing eChecks An eCheck is an electronic funds transfer that withdraws money directly from your buyer's bank account. It’s just like writing a check, only it is done electronically. When your buyer has a PayPal balance, or uses an Instant Transfer or a credit card, the money is instantly credited to the your PayPal account.
16 126 Processing eChecks Refunding eChecks May, 2005 Merchant User Manual and Integration Guide
17 Security Notification Validation Notification validation is the process you use to validate your IPN data. For more information about Notification Validation, see “Notification Validation ” on page 106. Button Encryption If you choose Button Encryption in the Button Factory, which is the default value, your website payments will be secure, thus both you and your customers remain protected.
17 Security Multi-User Access Multi-User Access PayPal’s Multi-User Access feature allows you to set up multiple logins and give others different levels of access to your PayPal account, so your employees only have access to the parts of your Paypal account that they need to complete their jobs.
Security Multi-User Access 17 Getting Started To use Multi-User Access: 1. Log in to your PayPal Business account. 2. Go to your Profile and click the Multi-User Access link. 3. Specify your Administrative Contact email address, which is the email address that will receive notifications about your account activity. 4. Add up to 9 separate logins to your account. For every login, select a User ID and password, and specify what account privileges the user has permission to access (e.g.
17 Security Using Secure Socket Layer (SSL) Using Secure Socket Layer (SSL) If you have contracted with a third-party hosting provider to operate your Web site, PayPal recommends contacting your provider to find out if you already have SSL capabilities or if you need to have SSL installed. Most hosting providers can activate SSL for your hosting account. If you are operating your own Web server, you will need to acquire and install your own SSL certificates.
A HTML Samples PayPal Buy Now and Donation Buttons HTML and Variables By understanding how your Buy Now Button HTML code and hyperlinks work, you can edit the attributes of your buttons or create appropriate Buy Now code “on the fly” for each payment. This can be used to collect aggregated payments with your shopping cart.
A HTML Samples PayPal Buy Now and Donation Buttons HTML and Variables
HTML Samples PayPal Buy Now and Donation Buttons HTML and Variables TABLE A.1 A HTML and Hyperlink Variables for Buy Now and Donations Buttons Name Character Length Description Item Information amount The price or amount of the purchase, not including shipping, handling, or tax. If omitted, this value will be editable by the customer at the time of purchase. item_name Description of item. If omitted, customer will see a field in which they have the option of entering an item name.
A HTML Samples PayPal Buy Now and Donation Buttons HTML and Variables TABLE A.1 134 HTML and Hyperlink Variables for Buy Now and Donations Buttons Character Length Name Description no_note Including a note with payment. If set to “1,” your customer will not be prompted to include a note. If omitted or set to “0,” your customer will be prompted to include a note. no_shipping The buyer’s shipping address. If omitted or set to “0,” your customer will be prompted to include a shipping address.
HTML Samples PayPal Buy Now and Donation Buttons HTML and Variables TABLE A.1 A HTML and Hyperlink Variables for Buy Now and Donations Buttons Character Length Name Description cpp_headerb order_color Sets the border color around the header of the payment page. The border is a 2pixel perimeter around the header space, which has a maximum size of 750 pixels wide by 90 pixels high. Valid character set is 6 character HTML Hex code in ASCII. This variable is not case-sensitive.
A HTML Samples PayPal Buy Now and Donation Buttons HTML and Variables TABLE A.1 136 HTML and Hyperlink Variables for Buy Now and Donations Buttons Character Length Name Description tax Transaction-based tax override variable. Set this to a flat tax amount you would like to apply to the transaction regardless of the buyer’s location. If present, this value overrides any tax settings that may be set in your Profile. If omitted, Profile tax settings (if any) will apply. tax_x The item tax amount.
HTML Samples PayPal Shopping Cart HTML and Variables A PayPal Shopping Cart HTML and Variables PayPal Shopping Cart HTML Rather than creating a separate button for every single item you wish to sell with the PayPal Shopping Cart, you can manipulate the Add to Cart HTML code to create different Add to Cart buttons.
A HTML Samples PayPal Shopping Cart HTML and Variables Shopping Cart Variables The Shopping Cart variables are the same as the Buy Now and Donation variables. The following table lists all of the variables that are specific to the Shopping Cart Button. For more information on the additional variables, please to the HTML and Hyperlink Variables section of the PayPal Buy Now Buttons HTML Code and Variables section of Appendix A. TABLE A.
HTML Samples PayPal Shopping Cart HTML and Variables A For more information on the additional variables, please to the HTML and Hyperlink Variables section of the PayPal Buy Now Buttons HTML Code and Variables section of Appendix A. Passing Individual Items to PayPal If your third-party shopping cart can be configured to pass individual items to PayPal, information about the items will be included in the buyer’s and seller’s History logs and notifications.
A HTML Samples PayPal Shopping Cart HTML and Variables TABLE A.4 Variables for Individual Items in Third-Party Shopping Carts Character Length Name Description shipping2_x The cost of shipping each additional piece (quantity of 2 or above) of item #x. handling_x The cost of handling for item #x. tax_x The tax amount for item #x. on0_x First option field name for item #x 64 os0_x First set of option value(s) for item #x. on0_x must be defined for os0_x to be recognized.
HTML Samples Prepopulating Your Customer’s PayPal Sign-Up A Prepopulating Your Customer’s PayPal Sign-Up If you have already collected your customer’s information, you can pass this information to PayPal to prepopulate the first page of a new customer’s sign-up. The fields and parameters are listed in the following table. You can pass all or none of this data, as necessary. While your customer’s sign-up page will be prepopulated, it will still be editable.
A HTML Samples Prepopulating Your Customer’s PayPal Sign-Up TABLE A.5 Prepopulation Variables for Website Payments Variable Value Requirements Character Limit night_ phone_b The 3-digit prefix for U.S. phone numbers, or the entire phone number for non-U.S. phone numbers, excluding country code. This will prepopulate the buyer’s home phone number. Numeric characters only. 3 night_ phone_c The 4-digit phone number for U.S. phone numbers. This will prepopulate the buyer’s home phone number.
HTML Samples Prepopulating Your Customer’s PayPal Sign-Up TABLE A.6 A Prepopulation Variables for Account Signup Requirements Character Limit business_ state Alphanumeric 2 business_ zip Numeric 5 business_ country Alphabetic 2 business_ cs_email Alphanumeric 128 business_cs _phone_a Numeric 3 business_ cs_phone_b Numeric 3 business_ cs_phone_c Numeric 4 business_ url Alphanumeric 128 Variable Value business_ night_phone _a The area code for U.S.
A HTML Samples Prepopulating Your Customer’s PayPal Sign-Up
B IPN and PDT Variables IPN and PDT variables are case-sensitive. All values are lowercase, except those for payment_status, which have an initial capital letter. Data Type. IPN posts contain only alphanumeric characters. Maximum Field Lengths. The maximum field length for each returned field is 127 characters, with the exception of the custom and memo fields, which have a maximum length of 255 characters. The unique PayPal Transaction ID is 17 characters long. URL Encoding.
B IPN and PDT Variables IPN Variables in All Posts IPN Variables in All Posts IPN Version: notify_version The value of the notify_version variable is the version number of Instant Payment Notification that makes the post. The current version of IPN is 1.6. Security Information: verify_sign The value of of verify_sign is an encrypted string used to validate the authenticity of the transaction. Buyer Information TABLE 17.
IPN and PDT Variables Basic Information B TABLE 17.1 IPN and PDT Variables: Buyer Information Character Length Variable Name Possible Values Description payer_ status verified unverified Customer has a Verified PayPal account. Customer has an Unverified PayPal account. Basic Information TABLE B.1 IPN and PDT Variables: Basic Information Variable Name Possible Values Character Length Description business Email address or account ID of the payment recipient (i.e., the merchant).
B IPN and PDT Variables Advanced and Custom Information Advanced and Custom Information TABLE B.2 IPN and PDT Variables: Advanced and Custom Information Variable Name Possible Values Character Length Description invoice Pass-through variable you can use to identify your Invoice Number for this purchase. If omittted, no variable will be passed back to you. 127 custom Custom value as passed by you, the merchant.
IPN and PDT Variables Shopping Cart Information TABLE B.3 B IPN and PDT Variables: Shopping Cart Information Variable Name Possible Values Description tax PayPal appends the number of the item (e.g., item_name1, item_name2). The tax_x is only included if there was a specific tax amount applied to a particular shopping cart item. Because profile tax may apply to other items in the cart, the sum of tax_x might not total to tax. option_ name1 PayPal appends the number of the item (e.g.
B IPN and PDT Variables Shopping Cart Information TABLE B.3 150 IPN and PDT Variables: Shopping Cart Information Variable Name Possible Values Description payment_ status CanceledReversal Completed Denied Failed Pending Refunded Reversed Processed Canceled-Reversal: This means a reversal has been canceled. For example, you won a dispute with the customer, and the funds for the transaction that was reversed have been returned to you.
IPN and PDT Variables Shopping Cart Information TABLE B.3 B IPN and PDT Variables: Shopping Cart Information Variable Name Possible Values Description pending_ reason address authorizatio n echeck intl multicurrency unilateral upgrade verify other This variable is set only if payment_status = Pending.
B IPN and PDT Variables Currency and Currency Exchange TABLE B.3 IPN and PDT Variables: Shopping Cart Information Variable Name Possible Values Description In the case of a refund, reversal, or canceled reversal, this variable contains the txn_id of the original transaction, while txn_id contains a new ID for the new transaction. Character length and limitations: 17 parent_txn_ id txn_type cart send_money web-accept cart: Transaction created by customer via the PayPal Shopping Cart feature.
IPN and PDT Variables Auctions TABLE B.4 B IPN and PDT Variables: Currency and Currency Exchange Information Variable Name Possible Values Description settle_ amount Amount that is deposited into the account’s primary balance after a currency conversion from automatic conversion (through your Payment Receiving Preferences) or manual conversion (through manually accepting a payment). settle_ currency Currency of settle_amount. exchange_ rate Exchange rate used if a currency conversion occurred.
B IPN and PDT Variables Mass Payment TABLE B.5 Variable Name IPN and PDT Variables: Auctions Possible Values Character Length Description This is a counter used for multi-item auction payments. It allows you to cumstomize your script to only count the mc_gross or payment_gross for the first IPN you receive from a multiitem auction (auction_multi_item), since each item from the auction will generate an Instant Payment Notification showing the amount for the entire auction.
IPN and PDT Variables Mass Payment TABLE B.6 B IPN and PDT Variables: Mass Pay Variable Name Possible Values Description mc_currency _x Transactionspecific for Multiple Currencies For Mass Pay payments, the currency of the amount and fee, where x is the record number.
B IPN and PDT Variables Subscriptions Variables Subscriptions Variables Along with other IPN variables, the following variables are included in Subscriptions IPNs. TABLE B.7 Subscriptions Variables Variable txn_type Possible Values subscrfailed subscrcancel subscrpayment Character Limit Description subscr_signup: subscription sign-up. subscr_cancel: subscription cancellation. subscr_failed: subscription payment failure. subscr_payment: subscription payment. subscr_eot: subscription’s end-of-term.
IPN and PDT Variables Subscriptions Variables TABLE B.7 B Subscriptions Variables Variable Possible Values Description mc_amount2 Amount of payment for trial period 2, regardless of currency (optional). mc_amount3 Amount of payment for regular subscription period, regardless of currency. mc_currency See introduction. For non-payment subscriptions IPNs (i.e., txn_type = signup, cancel, failed, eot, or modify), this is the currency of the subscription.
B IPN and PDT Variables Subscriptions Variables Variables for Each Subscription Event The following table shows which variables are associated and can be included in IPN posts with each subscription event type. About payment_status and txn_type with Subscription IPN. In IPN messages posted by Subscription events, the payment_status variable is sent only when a payment occurs. For all other events, the pertiunent variable is txn_type. TABLE B.
IPN and PDT Variables Subscriptions Variables TABLE B.
B IPN and PDT Variables Dispute Notification Variables TABLE B.
IPN and PDT Variables Dispute Notification Variables TABLE B.9 Variable Dispute Notification Variables Possible Values Description Case identification number. Format: PP-nnn-nnn-nnn where n is any numeric character. case_id case_type B complaint chargeback z z complaint: A buyer has logged a complaint through the PayPal Resolution Center. chargeback: A buyer has filed a chargeback with his credit card company, who has notified PayPal of the reason for the chargeback.
B IPN and PDT Variables PDT-Specific Variables PDT-Specific Variables The following variables apply only to PDT. TABLE B.10 PDT-Specific Variables 162 Variable Description tx The transaction ID/PDT token. st The transaction status. Pending, amt The amount of the transaction. cc Currency code. cm Custom message.
C Country Codes ISO 3166 Standard Country Codes PayPal relies on two-character country codes defined by International Standards Organization (ISO) 3166. TABLE C.
C Country Codes ISO 3166 Standard Country Codes TABLE C.
