Order Management Integration Guide For Professional Use Only Currently only available in English. A usage Professional Uniquement Disponible en Anglais uniquement pour l'instant.
PayPal Order Management 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. PayPal (Europe) Ltd. is authorised and regulated by the Financial Services Authority in the United Kingdom as an electronic money institution. PayPal FSA Register Number: 226056. Notice of Non-Liability PayPal, Inc.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 11 Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Differences between Instant Payment Notification (IPN) and Payment Data Transfer (PDT) 12 SSL Not Required for IPN . . . . . . . . . . . . . . . . . . . . . .
Contents Dispute Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Chapter 4 Downloadable History Log . . . . . . . . . . . . . . . . . 33 Customizing Your Downloadable History Log . . . . . . . . . . . . . . . . . . . . . . . . 34 Downloading Your History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Viewing Your Downloaded Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Appendix A IPN and PDT Variables . . . . . .
List of Tables Table 1.1 PayPal-Supported Currencies, Currency Codes, and Maximum Transaction Amounts 13 Table 4.1 IPN and PDT Variables: Buyer Information . . . . . . . . . . . . . . . . 40 Table A.1 IPN and PDT Variables: Basic Information . . . . . . . . . . . . . . . . . 41 Table A.2 IPN and PDT Variables: Advanced and Custom Information . . . . . . . . 42 Table A.3 IPN and PDT Variables: Shopping Cart Information . . . . . . . . . . . . 43 Table A.
List of Tables 6 August 2005 Order Management Integration Guide
List of Figures Figure 4.1 The Download My History Link . . . . . . . . . . . . . . . . 34 Figure 4.2 Customize My History Download . . . . . . . . . . . . . . . 35 Figure 4.3 Download History Page . . . . . . . . . . . . . . . . . . . 36 Figure 4.4 A Comma-Separated Value History log in a spreadsheet file. Figure 4.5 A comma-delimited history log in a text file Order Management Integration Guide August 2005 . 38 . . . . . . . . .
List of Figures 8 August 2005 Order Management Integration Guide
Preface This Document This release of the PayPal Order Management Integration Guide, a document that describes the PayPal features for managing orders, such as Payment Data Transfer (PDT), Instant Payment Notification (IPN), and Downloadbale History Log, replaces the version released in June, 2005. This document replaces portions of the Merchant User Manual and Integration Guide issued in April, 2005. Intended Audience This document is written for merchants who use PayPal to manage order information.
Preface Typeface How Used monospaced Pathnames or file names that appear in body text frames. Code-related names that appear in body text frames. Such names are used for functions, callbacks, arguments, data structures, and fields. For example: AbstractResponseType is the SOAP response type definition on which all PayPal API response methods are based. Components of Internet protocol requests and responses, such as HTTPS and FORM variables.
1 Introduction PayPal offers four payment notification methods for backend integration: z Email z Reporting Tools z Instant Payment Notification (IPN) z Payment Data Transfer (PDT) Email 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. Click the Profile subtab of the My Account tab. 2. Click the Notifications link in the Account Information column. 3.
Introduction Differences between Instant Payment Notification (IPN) and Payment Data Transfer (PDT) z 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.
Introduction PayPal-Supported Currencies PayPal-Supported Currencies The following currencies are supported by PayPal. TABLE 1.1 PayPal-Supported Currencies, Currency Codes, and Maximum Transaction 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.
Introduction PayPal-Supported Currencies 14 August 2005 Order Management Integration Guide
2 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. N O T E : You must enable Auto Return for Website Payments to use Payment Data Transfer. Auto Return brings your buyers back to your website immediately after payment completion. Auto Return applies to PayPal Website Payments, including Buy Now, Donations, Subscriptions, and Shopping Cart.
Payment Data Transfer How PDT 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. 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.
Payment Data Transfer How PDT Works 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. Step 6: A transaction token is passed to the return URL provided by the Widget Warehouse. The Widget Warehouse fetches the transaction token and retrieves the transaction details from PayPal via an HTTP POST.
Payment Data Transfer Enabling Payment Data Transfer Step 8: Bob receives an email receipt for this transaction, confirming his purchase and including a copy of the payment details, the Widget Warehouse's business information, and his confirmed shipping address. Enabling Payment Data Transfer To enable PDT: 1. Click the My Account tab. 2. Click the Profile subtab. 3. Click the Website Payment Preferences link, as shown in the following diagram. The Website Payment Preferences page opens.
Payment Data Transfer PDT and PayPal Account Optional 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. Getting and Using the Identity Token When you click Save and save your PDT preferences, a message appears at the top of the page indicating that you have successfully saved your preferences.
Payment Data Transfer PDT Notification Synch PayPal Account Optional is enabled by default. If the merchant has turned on Payment Data Transfer and has not disabled PayPal Account Optional, a new user will not be automatically directed back to the merchant website, but will be given the option to return. When the buyer clicks Continue, the transaction ID associated with the transaction is sent.
Payment Data Transfer PDT Notification Synch PayPal Response to POST PayPal responds to the post with a single word on one line in the body of the response: SUCCESS or FAIL. When you receive a SUCCESS response, the rest of the body of the response is the transaction details, one per line, in the format key=value where key and value are both be URL-encoded strings. This response data needs to be parsed appropriately and then URL-decoded.
Payment Data Transfer Preventing Fraud Preventing Fraud In order to prevent fraud, PayPal recommends that your programs verify the following: z txn_id is not a duplicate to prevent someone from reusing an old, completed transaction. z receiver_email is an email address registered in your PayPal account, to prevent the payment from being sent to a fraudulent account. z Other transaction details, such as the item number and price, to confirm that the price has not been changed.
3 Instant Payment Notification (IPN) 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. z Automate your fulfillment operations. z Store transaction information in your own database.
Instant Payment Notification (IPN) How IPN POSTs Are Sent How IPN POSTs 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.
Instant Payment Notification (IPN) Setting Up IPN Step 5: After verifying the correctness of the data from IPN, you can update your database with the IPN data and process the purchase. 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.
Instant Payment Notification (IPN) IPN Notification and Notification Validation IPN Notification and Notification Validation After your server receives Instant Payment Notification, you must confirm that you received it. This is known as notification validation, which is a means for PayPal to help you prevent spoofing or “man-in-the-middle” attacks. You have two methods by which you can validate the notification: 1. Sending a shared secret, described in “Shared Secret Validation” on page 27.
Instant Payment Notification (IPN) IPN Notification and Notification Validation Shared Secret Validation The first and recommended method for notification validation is to use a shared secret on individual payment transactions. Add a shared secret variable and value to the value of the notify_url variable to which the IPN data is posted after a payment is made.
Instant Payment Notification (IPN) Using IPN with Multiple Currencies PayPal Response to Postback PayPal responds to the postback with a single word in the body of the response: VERIFIED or INVALID. When you receive a VERIFIED response, perform the following checks: 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.
Instant Payment Notification (IPN) Using IPN with Multiple Currencies 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. Examples of Multi-currency IPN Variables IPNs that use the payment_gross variable will have the following multi-currency variables added.
Instant Payment Notification (IPN) Using IPN with Multiple Currencies payment_gross = payment_fee = mc_gross =100 mc_fee = 3.00 mc_currency = CAD Example 3 If the account is set to automatically convert payments, these variables will be used to show the conversion. This example is for a user with a USD balance who receives a payment of 100 GBP: EXAMPLE 3.3 Mutli-currency IPN: Automatic Conversion of GBP Payment payment_status = Completed payment_gross = payment_fee = mc_gross = 100 mc_fee = 3.
Instant Payment Notification (IPN) Using IPN with Multiple Currencies EXAMPLE 3.6 Pending - Accept to Currency Balance payment_status = Completed payment_gross = payment_fee = mc_gross = 100 mc_fee = 3.00 mc_currency = GBP If the payment is denied: EXAMPLE 3.
Instant Payment Notification (IPN) Dispute Notification Dispute Notification Buyers can register claims about payments; such claims are called cases. PayPal notifies merchants about new cases with email and with IPN. There are two kinds of cases: z Complaint: A buyer has used the PayPal Resolution Center to register a claim about a payment to a merchant. N O T E : After notification about a complaint claim, merchants must log in to PayPal to use the Resolution Center to respond to the case.
4 Downloadable History Log PayPal’s Downloadable History Log makes it easier and more efficient to track, sort and print transactions from your PayPal account. Download your transaction history into one of several available file formats outlined in this document so that you can view and store your transaction history offline.
Downloadable History Log Customizing Your Downloadable History Log Customizing Your Downloadable History Log Business or Premier PayPal account holders can customize their Downloadable History Log at any time. z Add info to, or remove from, your Downloadable History Log z Modify how information is displayed in your account For example, you can display a buyer's shipping address in a single column rather than multiple columns. Here’s how: 1. Log in to your PayPal account. 2.
Downloadable History Log Customizing Your Downloadable History Log FIGURE 4.2 Customize My History Download 5. A list of items appears. This is where you can select your preferences to customize your Downloadable History Log. 6. After modifying your selections, click Save.
Downloadable History Log Downloading Your History Downloading Your History Follow the instructions below to download your transaction history. 1. Log in to your PayPal account. 2. Click the History subtab under the My Account tab. 3. Click the Download My History link in the Reporting Tools box. FIGURE 4.3 Download History Page 4. On the next page, specify the date range. (You can check one of the boxes below to ignore previously downloaded transactions and transactions older than 30 days). 5.
Downloadable History Log Viewing Your Downloaded Log Viewing Your Downloaded Log As detailed in the previous section, your Downloadable History Log can be saved and viewed in any of the following file formats: z Comma-separated value (CSV) plain text file for use with spreadsheet programs z Tab-delimited plain text file z Intuit (Quicken/QuickBooks) file For automated file processing and reconciliation applications, PayPal recommends you use comma-delimited or tab-delimited formats.
Downloadable History Log Viewing Your Downloaded Log FIGURE 4.4 A Comma-Separated Value History log in a spreadsheet file. FIGURE 4.5 A comma-delimited history log in a text file Once the file is formatted, import the file into whatever program you use for reconciliation purposes.
A 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, Maximum Field Lengths, and URL Encoding IPN posts contain only alphanumeric characters. The maximum field length for each returned field is 127 characters, with the following exceptions: z custom has a maximum length of 255 characters. z memo has a maximum length of 255 characters.
IPN and PDT Variables test_ipn Variable in Sandbox test_ipn Variable in Sandbox In the Sandbox environment, IPN includes the additional variable test_ipn with a value of 1 (one). The purpose of test_ipn is to provide testing programs a means to differentiate between Sanbox IPN and live IPN. 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.
IPN and PDT Variables Basic Information TABLE 4.1 IPN and PDT Variables: Buyer Information Description Character Length address_ street Customer’s street address. 200 address_zip Zip code of customer’s address. 20 first_name Customer’s first name 64 last_name Customer’s last name 64 payer_ business_ name Customer’s company name, if customer represents a business 127 payer_email Customer’s primary email address. Use this email to provide any credits. 127 payer_id Unique customer ID.
IPN and PDT Variables Advanced and Custom Information TABLE A.1 IPN and PDT Variables: Basic Information Variable Name Possible Values Character Length Description quantity Quantity as entered by your customer or as passed by you, the merchant. If this is a shopping cart transaction, PayPal appends the number of the item (e.g. quantity1, quantity2). receiver_ email Primary email address of the payment recipient (i.e., the merchant).
IPN and PDT Variables Shopping Cart Information TABLE A.2 IPN and PDT Variables: Advanced and Custom Information Variable Name Possible Values Character Length Description option_ selection2 Option 2 choice as entered by your customer. If this is a shopping cart transaction, see Table A.3, “IPN and PDT Variables: Shopping Cart Information” on page 43 for more information. tax Amount of tax charged on payment. If this is a shopping cart transaction, see Table A.
IPN and PDT Variables Shopping Cart Information TABLE A.3 IPN and PDT Variables: Shopping Cart Information Variable Name Possible Values option_ name1 PayPal appends the number of the item where x represents the number of the shopping cart detail item (e.g., option_name1, option_name2). option_ name2 PayPal appends the number of the item where x represents the number of the shopping cart detail item (e.g., option_name2, option_name2). option_ selection1_ PayPal appends the number of the item (e.g.
IPN and PDT Variables Shopping Cart Information TABLE A.3 IPN and PDT Variables: Shopping Cart Information Variable Name Possible Values Description payment_ type echeck instant echeck: This payment was funded with an eCheck. instant: This payment was funded with PayPal balance, credit card, or Instant Transfer. pending_ reason address authorization echeck intl multi-currency unilateral upgrade verify other This variable is set only if payment_status = Pending.
IPN and PDT Variables Currency and Currency Exchange TABLE A.3 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 variable is included only 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. txn_id A unique transaction ID generated by the PayPal system.
IPN and PDT Variables Auctions TABLE A.4 IPN and PDT Variables: Currency and Currency Exchange Information Variable Name Possible Values Description payment_fee Transactionspecific for USD payments only USD transaction fee associated with the payment. payment_gross minus payment_fee equals the amount deposited into the receiver email account. Is empty for non-USD payments. This is a legacy field replaced by mc_fee.
IPN and PDT Variables Mass Payment Mass Payment TABLE A.
IPN and PDT Variables Subscriptions Variables TABLE A.
IPN and PDT Variables Subscriptions Variables TABLE A.7 Subscriptions Variables Variable Description subscr_ effective Date when the subscription modification will be effective (only for txn_type = subscr_modify). period1 (optional) Trial subscription interval in days, weeks, months, years (example: a 4 day interval is “period1: 4 D”). period2 (optional) Trial subscription interval in days, weeks, months, or years. period3 Regular subscription interval in days, weeks, months, or years.
IPN and PDT Variables Subscriptions Variables TABLE A.7 Variable Subscriptions Variables Possible Values Description username (optional) Username generated by PayPal and given to subscriber to access the subscription. password (optional) Password generated by PayPal and given to subscriber to access the subscription (password will be encrypted). subscr_id ID generated by PayPal for the subscriber.
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 A.
IPN and PDT Variables Subscriptions Variables TABLE A.
IPN and PDT Variables Dispute Notification Variables TABLE A.
IPN and PDT Variables Dispute Notification Variables TABLE A.9 Variable Dispute Notification Variables Possible Values Case identification number. Format: PP-nnn-nnn-nnn where n is any numeric character. case_id case_type Description 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, which has notified PayPal of the reason for the chargeback.
IPN and PDT Variables PDT-Specific Variables PDT-Specific Variables The following variables apply only to PDT. TABLE A.
IPN and PDT Variables PDT-Specific Variables August 2005 57
IPN and PDT Variables PDT-Specific Variables 58 August 2005
B TABLE B.1 Downloadable History Log Columns and Values Downloadable History Log Columns and Values Column Heading Description Format Date Date transaction was initiated (according to PayPal system time, US-Pacific time zone). Log sorted in reverse chronological order by Date (most recent first) [M]M/[D]D/Y YYY Time Time transaction was initiated (according to PayPal system time, US-Pacific time zone). HH:MM:SS Timezone The time zone used for recording transactions in your PayPal account.
Downloadable History Log Columns and Values TABLE B.
Downloadable History Log Columns and Values TABLE B.
Downloadable History Log Columns and Values TABLE B.
Downloadable History Log Columns and Values TABLE B.
Downloadable History Log Columns and Values TABLE B.
Downloadable History Log Columns and Values TABLE B.
Downloadable History Log Columns and Values 66 August 2005 Order Management Integration Guide
C Country Codes ISO 3166 Standard Country Codes PayPal relies on two-character country codes defined by International Standards Organization (ISO) 3166. TABLE C.
Country Codes ISO 3166 Standard Country Codes TABLE C.
Country Codes ISO 3166 Standard Country Codes TABLE C.
Country Codes ISO 3166 Standard Country Codes 70 August 2005
Index Symbols _notify-synch 20 _notify-validate 27 A Account Optional and PDT 19 address 45 address_city 40 address_country 40 address_country_code 40 address_name 40 address_state 40 address_street 41 address_zip 41 amount1 50 amount2 50 amount3 50 amt 56 at variable for PDT 20 auction_buyer_id 47 auction_closing_date 47 auction_multi_item 47 auth_amount 43 auth_exp 43 auth_id 43 auth_status 43 authorization 45 Auto Return and PDT 19, 21 B business 41 C Canceled-Reversal 44 cart 46 case_creation_date 5
Index VERIFIED response 28 item_name 41 item_number 41 option_selection2_x 44 other 45 P L last_name 41 M masspay_txn_id_x 48 mc_amount1 50 mc_amount2 50 mc_amount3 50 mc_currency 29, 46, 50 mc_currency_x 48 mc_fee 29, 46, 47 mc_fee_x 48 mc_gross 29, 46 mc_gross_x 43, 48 mc_handling 46 mc_handling_x 43 mc_shipping 46 mc_shipping_x 43 memo 42 merchandise 55 multi-currency 45 multiple currencies 28 N new_case 54 non_receipt 55 not_as_described 55 notification synch 20 notification validation 26, 27 notify
Index recurring 50 Refunded 44 remaining_settle 43 residence_country 41 Resolution Center 32 retry_at 50 Reversed 44 verify_sign 40 Voided 44 W web 46 S send_money 46 settle_amount 47 settle_currency 47 special 55 st 56 subscr_cancel 49 subscr_date 49 subscr_effective 50 subscr_eot 49 subscr_failed 49 subscr_id 51 subscr_modify 49 subscr_payment 49 subscr_signup 49 SUCCESS or FAIL response in PDT 21 T tax 43, 46 test_ipn 40 tx 56 tx variable for PDT 20 txn_id 46, 54 txn_type 46, 49, 54 U unauthorized 5
Index 74 August 2005 Order Management Integration Guide
