Home

PayPal Order Management - 2006 Integration Guide

Contents

1. My Account Send Money Request Money Merchant Services Auction Tools Products amp Services Overview AddFunds Withdraw History Resolution Center Profile History Monthly Account Statements Reporting Tools View up to three months of transaction history in one convenient place e Download My History Get Monthly Account Statements s DES Learn More e Advanced Search Search Choose the Activity Type and the time period in which to search Click Search to see results below Show Al Activity Simple View Within The Past Day 2 e em a By B Month Day Year Month Day Year All Activity Simple View from Sep 7 2005 to Oct 7 2005 Das e 8 25 Date Type To From Name Email Status Details Action Gross Fee Net Amount None Monthly Account Statements After you activate this feature you can view Order Management Integration Guide October 2006 39 a Transaction History and Reporting Tools Online History Searching monthly account statements of your transaction records New statements become available on the 15th of each month and the statements are retained online for up to three months To activate monthly account statements 1 Click Get Monthly Account Statements on the History page 2 On the displayed page click the Yes radio button My Account Send Money Request Money Merchant Services Auction Tools Products amp Services Overview AddFunds Withdraw History R
2. dd 27 Chapter 3 Instant Payment Notification IPN 29 AboutlPN ao 2 goed 29 Setting Up IPN ioe aa i e a a e a a ee 30 Activating IP IN uuu oe as ker Aces ok se ee geek Gow Gar ee M d p oe kes 30 Setting Up an IPN Processing 31 Order Management Integration Guide October 2006 UN Contents IPN Notification Validation Preventing 31 Shared Secret Per Transaction or by Profile Setting 32 Shared Secret Validation 32 Your HTTPS 1 33 Using IPN with Multiple Currencies 34 mc gross and ME fee s sa ES ON ee 34 ME CUIENGCY os ox eom ok m RC UE ee eee ee a 35 payment gross and payment 35 Examples of Multi currency IPN Variables 35 Chapter 4 Transaction History and Reporting Tools 39 Monthly Account 39 Online History Searching a 40 Basic Search 40 Advanced Search Key 5 41 Download My History 0 42 Choosing a Date 42 Selecting
3. gives a brief overview of the PayPal features for order management discussed in this guide Chapter 2 Payment Data Transfer describes how PDT works and how to set it up Chapter 3 Instant Payment Notification IPN describes how IPN works and how to set it up Chapter 4 Transaction History and Reporting Tools describes monthly account statements online transaction search the Downloadable History Log and dispute reports Appendix A IPN and PDT Variables is a detailed description of all variables and values returned by IPN or PDT Appendix B Downloadable History Log Columns and Values describes the columns and values that can be included in the Downloadable History Log Order Management Integration Guide October 2006 11 Notational Conventions Notational Conventions This document uses typefaces to identify the characteristics of text These typefaces and the characteristics they imply are described below Typeface serif italics monospaced Serif bold San serif oblique How Used A document title A term being discussed or defined For example A file is a readable or writable stream of characters Boolean values not keywords For example The function returns true if it encounters an error 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 structur
4. 30 2005 to Sep 29 2005 Transaction Type Counterparty ID Date Amount Reason Filed Status Details Email None Download Dispute Report Return to History Programmatic Access to Dispute Report The Downloadable Dispute Report DDR provides merchants with a regular report of newly created disputes and changes in the status of those cases that are already open and are in the midst of processing The report is designed for the merchant that processes large volumes of payments Thus while the report resembles the Dispute Report available via the Resolution Center within the PayPal site the DDR differs in that it contains all open records and the invoice ID which can be used to track dispute cases based on your transactional identifiers The DDR cannot filter on open records Note To use this feature you must sign up for the report through your PayPal Account Manager Order Management Integration Guide October 2006 47 48 Transaction History and Reporting Tools Dispute Report Content of the Report The report contains information about all chargebacks and buyer complaints generated for your account This report does not contain information about ACH returns of PayPal unauthorized complaints First DDR Report When you first sign up for the DDR the report contains e All open chargebacks regardless of the date the case was created or the current status of the case e All open buyer complaints regardless o
5. PDT Variables Website Payments Standard and Refund Information on page 55 for more information Total shipping amount associated with the transaction If this is a shopping cart transaction see Table A 4 IPN and PDT Variables Website Payments Standard and Refund Information on page 55 for more information 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 If this amount is negative it signifies a refund or reversal and either of those payment statuses can be for the full or partial amount of the original transaction fee NOTE This is a deprecated field Use mc fee instead 60 October 2006 Order Management Integration Guide IPN and PDT Variables Auctions TABLE A 5 PN and PDT Variables Currency and Currency Exchange Information Variable Possible Character Name Values Description Length payment_ Transaction Full USD amount of the customer s payment before transaction gross specific for fee is subtracted Will be empty for non USD payments This is USD payments a legacy field replaced by mc gross If this amount is negative only it signifies a refund or reversal and either of those payment statuses can be for the full or partial amount of the original transaction settle_ Amount that is deposited into the account s primary balance amount after a currency conversion fro
6. SAUDI ARABIA SENEGAL SERBIA AND MON TENEGRO SEYCHELLES SIERRA LEONE SINGAPORE SLOVAKIA SLOVENIA SOLOMON ISLANDS SOMALIA SOUTH AFRICA SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS SPAIN SRI LANKA SUDAN SURINAME SVALBARD AND JAN MAYEN SWAZILAND SWEDEN SWITZERLAND SYRIAN ARAB REPUB LIC TAIWAN PROVINCE OF CHINA TAJIKISTAN Code ST SA SN CS SC SL SG SK SI SB SO ZA GS ES LK SD SR SJ SZ SE CH SY TW Country TANZANIA UNITED REPUBLIC OF THAILAND TIMOR LESTE TOGO TOKELAU TONGA TRINIDAD AND TOBAGO TUNISIA TURKEY TURKMENISTAN TURKS AND CAICOS ISLANDS TUVALU UGANDA UKRAINE UNITED ARAB EMIR ATES UNITED KINGDOM UNITED STATES UNITED STATES MINOR OUTLYING ISLANDS URUGUAY UZBEKISTAN VANUATU VENEZUELA VIET NAM VIRGIN ISLANDS BRIT ISH Code TZ TH TL TG TK TO TT TN TR TM TC TV UG UA AE GB US UM UY UZ VU VE VN VG mm Country Codes 84 Country VIRGIN ISLANDS U S WALLIS AND FUTUNA WESTERN SAHARA YEMEN ZAMBIA ZIMBABWE Code VI EH YE ZM ZW Index A activities 41 address 58 address_city 52 address_country 52 address_country_code 52 address_name 52 address_state 52 address_status 52 address_street 52 address_zip 52 adjustment 68 All Activity Advanced View 41 amount 64 amount2 64 amount3 64 amt 69 auction_buyer_id 61 auction_closing_date 61 auct
7. lic Zip Postal Code Zip Postal Code of shipping address address zip as specified by counterparty Country Country of shipping address as address specified by counterparty country Order Management Integration Guide October 2006 77 a Downloadable History Log Columns and Values TABLE B 1 Downloadable History Log Columns and Values Payment Button Related IPN Column Heading Description Format Variable Variable Balance Account balance at time of signed decimal transaction Balance is reported in the currency of the transaction The Balance column can show in some instances which indicates that showing a balance is not appropriate for these kinds of transaction 78 October 2006 Order Management Integration Guide Note This table lists country codes Country Codes defined by ISO 3166 1 Table 1 Country Codes Country AFGHANISTAN ALAND ISLANDS ALBANIA ALGERIA AMERICAN SAMOA ANDORRA ANGOLA ANGUILLA ANTARCTICA ANTIGUA AND BAR BUDA ARGENTINA ARMENIA ARUBA AUSTRALIA AUSTRIA AZERBAIJAN BAHAMAS BAHRAIN BANGLADESH BARBADOS Code AF AX AL DZ AS AD AO AI AQ AG AR AM AW AU AT AZ BS BH BD BB Country BELARUS BELGIUM BELIZE BENIN BERMUDA BHUTAN BOLIVIA BOSNIA AND HERZE GOVINA BOTSWANA BOUVET ISLAND BRAZIL BRITISH INDIAN OCEAN TERRITORY BRUNEI DARUSSALAM BULGARIA BURKINA FASO BURUNDI CAMBODIA CAMEROON CANADA CAPE VERDE CAYMAN ISLANDS
8. message relating to the complaint You should compare the IPN variable parent txn id of all IPN messages to match the chargeback with the complaint October 2006 Order Management Integration Guide Transaction History and Reporting Tools Dispute Report IPN variables for cases include the type of case the reason and other information about the case For details about all variables and their possible values see Dispute Notification Variables on page 68 With the dispute report you can focus only on transactions that are disputed by customers for some reason FIGURE 4 5 Dispute Report My Account Merchant Services f Auction Tools Products amp Services Overview Add Funds Withdraw History Resolution Center Profile Dispute Report Your Dispute Report lets you view sort and download the details of the buyer complaint and chargeback cases associated with your account Note The data in this report is updated once each day Any changes to cases after the daily update will be captured the next day Search Choose the type of disputes to view and the time period in which to search Then click Search to see your results Download To download the information shown in the table click Download Dispute Report Type fan Disputes Status fu Nm C Within The Past Day From n 16 005 ef Boos Month Day Year Month Day Year Disputes and Requests All Disputes Aug
9. the currency of the amount and fee where xX specific for x is the record number the mass pay item multiple currencies mc_fee_x Transaction For Mass Payments the transaction fee associated with the specific for payment where x is the record number the mass pay item multiple Currencies mc gross x Transaction The gross amount for the amount where x is the record number specific for the mass pay item Multiple Currencies payment For Mass Payments the first IPN is the date time when the 28 date record set is processed and the second IPN is the date time when all payments are completed returned Format HH MM SS DD Mmm YY YYYY PST payment fee Transaction If the payment is EUR then the value is the same as that for cix specific for mc fee x where x is the record number if the currency is not EUR payments EUR then this is an empty string only NOTE This is a deprecated field Use mc_fee_x instead payment_ Transaction If the payment is USD then the value for this is the same as that gross x specific for for the mc gross x where x is the record number the mass USD payments item If the currency is not USD this is an empty string only NOTE This is a deprecated field Use mc_gross_x instead payment_ Completed Completed For Mass Payments this means that all of your status Denied payments have been claimed or after a period of 30 days Process d unclaimed payments have been returned to you Denied For Mass Payments this m
10. Code BY BE BZ BJ BM BT BO BA BW BV BR IO BN BG BF BI KH CM CA CV KY 79 mm Country Codes 80 Country CENTRAL AFRICAN REPUBLIC CHAD CHILE CHINA CHRISTMAS ISLAND COCOS KEELING ISLANDS COLOMBIA COMOROS CONGO CONGO THE DEMO CRATIC REPUBLIC OF THE COOK ISLANDS COSTA RICA COTE D IVOIRE CROATIA CUBA CYPRUS CZECH REPUBLIC DENMARK DJIBOUTI DOMINICA DOMINICAN REPUBLIC ECUADOR EGYPT EL SALVADOR Code CF TD CL CN CX CC CO CG CD CK CR CI HR CU CZ DK DJ DM DO EC EG SV Country EQUATORIAL GUINEA ERITREA ESTONIA ETHIOPIA FALKLAND ISLANDS MALVINAS FAROE ISLANDS FIJI FINLAND FRANCE FRENCH GUIANA FRENCH POLYNESIA FRENCH SOUTHERN TERRITORIES GABON GAMBIA GEORGIA GERMANY GHANA GIBRALTAR GREECE GREENLAND GRENADA GUADELOUPE GUAM GUATEMALA GUERNSEY Code GQ ER EE ET FK FO FJ FI FR GF GM GE DE GH GI GR GL GD GP GU GT GG Country GUINEA GUINEA BISSAU GUYANA HAITI HEARD ISLAND AND MCDONALD ISLANDS HOLY SEE VATICAN CITY STATE HONDURAS HONG KONG HUNGARY ICELAND INDIA INDONESIA IRAN ISLAMIC REPUB LIC OF IRAQ IRELAND ISLE OF MAN ISRAEL ITALY JAMAICA JAPAN JERSEY JORDAN KAZAKHSTAN KENYA KIRIBATI KOREA DEMOCRATIC PEOPLE S REPUBLIC OF Code GN GW GY HT HM VA HN HK HU IS IN ID IR IQ IE IM IL IT JM JP J
11. ET ace LEK ae 61 Mass Payment xem sed mo RUE be S K KG bo ew d m bone i 62 Subscriptions Variables 64 Dispute Notification Variables 68 PDT Specific 69 Appendix B Downloadable History Log Columns and Values71 Appendix C Country Codes 79 Index 85 Order Management Integration Guide October 2006 m Contents 6 October 2006 Order Management Integration Guide Table P 1 Table 1 1 Table 4 1 Table 4 2 Table A 1 Table A 2 Table A 3 Table A 4 Table A 5 Table A 6 Table A 7 Table A 8 Table A 9 Table A 10 Table A 11 Table B 1 Table 1 Order Management Integration Guide List of Tables Revision History 13 PayPal Supported Currencies and Currency Codes for Transactions 17 Online Search Selectable Activity Types 41 Advanced Transaction Search Key Fields 41 IPN and PDT Variables Buyer Information 52 IPN and PDT Variables Basic Information 53 IPN and PDT Variables Advanced and Custom Information 54 IPN and PDT Variables Website Payments Standard and Refund Information 55 IPN and PDT Variables Currency and Currency Exchange Information 60 IPN and PDT Variables 61 IPN and PDT Variables Mass Payment 6
12. Notification Variables on page 68 PDT Specific Variables on page 69 Transaction Specifc Variable Values Unless otherwise indicated in the table column labeled Possible Values the value of an IPN or PDT variable is always specific to the transaction whose information is being posted 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 Sandbox IPN and live IPN Order Management Integration Guide October 2006 51 52 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 Note The value notify version is a means for PayPal to track versions of IPN There is no need for your programs to store this value or query it 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 A 1 PN and PDT Variables Buyer Information Variable Possible Character Name Values Description Length address_ City of customer s address 40 city address_ Country of customer s address 64 country address_ Two character ISO 3166 country code 2 country_ code address_ Name used with address includ
13. October 2006 Order Management Integration Guide Transaction History and Reporting Tools 8 Dispute Report 3 Click the Multi User Access link under the Account Information column to open the Multi User Access page 4 Click the Add button On the Multi User Access page enter the requested information into the fields provided 5 Select the checkboxes next to each of the choices that you want the alias to have 6 Click Save Your new user and alias appear on the Multi User Access page along with a confirmation message that you have successfully added a new user to your account Step 3 Write Code to Download the Report from the PayPal Server Write code to request the report from a PayPal server The code must send an HTTP POST to the PayPal server The POST must be sent from a secure server that uses HTTPS PayPal does not accept requests from servers using HTTP You can automate which details you want to be prioritized in your Settlement File reports by assigning values as depicted in the sample HTML code The HTML code below is an example of the values that your DDR may contain In the following example the uname value is the alias created using the Multi User Access feature lt FORM ACTION https www paypal com us DISPUTE REPORT SCHED LOGIN ETHOD post gt lt INPUT TYPE hidden NAME day VALUE 16 lt INPUT TYPE hidden NAME month VALUE 09 lt INPUT TYPE hidden NAME year VALUE 2006 lt INPUT TYPE h
14. Online Search Selectable Activity Types TABLE 4 1 Online Search Selectable Activity Types All Activity Advanced Fee Reversals Open Authorizations View Sent or Received All Activity Simple Subscriptions Shipping PayPal Buyer Credit View Payments Sent or BillPay Transactions Balance Affecting Received Transactions Mass Payments Refunds eChecks Money Requests Currency Conversions Preapproved Payments Funds Added or Balance Transfer Gift Certificates Withdrawn All Activity Advanced View is the same as All Activity Simple View except it also includes a Balance column The Balance column can show in some instances which indicates that showing a balance is not appropriate for these kinds of transaction Advanced Search Key Fields For an advanced search specify the dates in the same manner as you do for basic search as detailed in Basic Search Time Periods on page 40 You can limit your search to the following fields TABLE 4 2 Advanced Transaction Search Key Fields Field Matching Criteria Email The text you enter must exactly match an email address Transaction ID Exact match Last Name Any part of the text you enter can match For example the text mit matches Smith and Mitty Last Name First Name part of text can match Receipt ID Exact match Item Number Exact match Order Management Integration Guide October 2006 41 a Transaction History and Reporting Tools Downl
15. Transfer PDT Email You will receive an email notification in the following cases e Successful Payment e Pending Payment e 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 Find the Payment Notifications heading and clear the I receive PayPal Website Payments and Instant Purchase checkbox 4 Click Save Reporting PayPal s Reporting Tools provide you with the information you need to effectively measure and manage your business With PayPal s Reporting Tools you can e Analyze your revenue sources to better understand your customers buying behavior e Automate time consuming bookkeeping tasks e Accurately settle and reconcile transactions Available reports e Monthly Account Statements View a summary of all credits and debits that have affected your account balance each month Order Management Integration Guide October 2006 15 Um Introduction Differences between Instant Payment Notification IPN and Payment Data Transfer PDT e Merchant Sales Reports Settlement Report STL Contains only the records of all balance effecting daily transactions Can be coordinated with Settlement System or created independently of the moving of money ransactions Detail Report TDR Status of all transactions including non complete transactions such as eCheck
16. X subscr signup cancel modify failed eot Currency and Exchange information mc gross X X mc fee X X mc currency X X X X X X X settle amount X X exchange rate X X payment gross X X X payment fee X Buyer Information first name X X X X X X X October 2006 Order Management Integration Guide IPN and PDT Variables EN Mass Payment TABLE A 9 IPN Variables with Each Subscription Event Payment Payment Multi Variable Signup Cancel Modify USD Currency Refund Failed last_name X X X X X X X payer business X X X X X X name address name X X X X X X address street X X X X X X address city X X X X X X address state X X X X X X address zip X X X X X X address X X X X X X country payer email X X X X X X X payer id X X X X X X X payer status X X X X X X X payment type X X Subscription Information subscr date X X X subscr X effective periodl X X X period2 x X X period3 X X X amount 1 X X X amount2 X X X amount3 X X X mc amounti X X X mc amount2 X X X recurring X X X reattempt X X X retry at X Order Management Integration Guide October 2006 67 68 IPN and PDT Variables Dispute Notification Variables TABLE 9 Variables with Each Subscription Event Payment Payment Multi Variable Signup Cancel Modify USD Currency Refund Failed recur_times X X X username X X X X X X X password X X X X X X X subscr id X X X X X X X Dispute Notification Variables TABLE A 10 Dispute No
17. a File Format and Transaction Categories 42 Completed Transactions Since Last 43 Customizing the Download Selecting Transaction Fields 43 Transaction Reconciliation with the Balance Impact Column 45 Lifecycle of a Transaction Status 45 Net Amount 46 Dispute Report s x uw cae d d Ak odd o oe OR a OR y Xx 46 Programmatic Access to Dispute Report 47 Appendix A IPN PDT Variables 51 About These Tables 51 Transaction Specifc Variable 51 test ipn Variable in 5 51 IPN Variables in Al Posts 52 IPN Version 52 Security Information verify sign 1 52 Buyer Information 0 52 Basic Information uxo ROUES RU d RR Ue UR RA 5 Advanced and Custom Information 54 Website Payments Standard and Refund 55 Currency and Currency Exchange 60 4 October 2006 Order Management Integration Guide Contents AUCHONS 2
18. as passed by you the merchant Or if not passed by 127 you as entered by your customer If this is a shopping cart transaction PayPal will append the number of the item e g item name 1 item name 2 and so forth item number Pass through variable for you to track purchases It will get 127 passed back to you at the completion of the payment If omitted no variable will be passed back to you 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 quantityl quantity2 Order Management Integration Guide October 2006 53 54 IPN and PDT Variables Advanced and Custom Information TABLE A 2 IPN and PDT Variables Basic Information Variable Possible Character Name Values Description Length receiver_ Primary email address of the payment recipient that is the 127 email merchant If the payment is sent to a non primary email address on your PayPal account the receiver email is still your primary email NoTE The value of this variable is normalized to lowercase characters receiver_id Unique account ID of the payment recipient i e the merchant 13 This is the same as the recipient s referral ID Advanced and Custom Information TABLE IPN and PDT Variables Advanced and Custom Information Variable Possible Character Name Values Description Length custom Custom value as passed by you the mercha
19. as shown in the following diagram Thank you for your payment Your transaction has been completed and a receipt for your purchase has been emailed to you You may log into your account at www paypal com to view details of this transaction Thank you for your payment Your transaction has been completed Widget 152 50 Email bdeboe merchantty Ship to Bob Deboe 1234 Main Street Walnut Creek CA 95599 Please print this page for your records A receipt for your purchase has also been emailed to you Global Industries Inc Al nghts reserved 2003 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 irm tam or VE Protect Your Account Info Dear Bob Deboe Make sure you never provide your 4 assword to fraudulent websites This email confirms that you Bob Deboe have paid P Widget Warehouse 162 50 using PayPal To safely and securely access the PayPal website or your account open up a new web browser e g Internet Explorer or Netscape and type in the PayPal URL https www paypal com to be Payment Details sure you are on the real PayPal site Amount 162 50 USD PayPal will never ask you to enter your Transaction ID 78H54514UY26 password in an email Quantity 1 pu as Widget EE Carm Protect Your Password You
20. complaint about the transaction from your customer refund A reversal has occurred on this transaction because you have given the customer a refund other A reversal has occurred on this transaction due to a reason not listed above remaining_ Transaction Remaining amount that can be captured with Authorization and settle specific Capture shipping Transaction Shipping charges associated with this transaction specific Format unsigned no currency symbol two decimal places 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 transaction auth Authorization and Capture transaction entity reauth entity rder payment txn_id A unique transaction ID generated by PayPal 19 txn_type cart cart Transaction created by a customer express_ e Via the PayPal Shopping Cart feature checkout e Via Express Checkout when the cart contains multiple send_money items virtual_ express_checkout Transaction created by Express terminal Checkout when the customer s cart contains a single item web accept send money Transaction created by customer from the Send Money tab on the PayPal website virtual_terminal Transaction created with Virtual Terminal web accept Transaction created by customer via Buy Now Donation or Auct
21. have any problems with this documentation please email us by following the instructions below Describe the error or problem as completely as possible and give us the document title the date of the document located at the foot of every page and the page number or page range To contact Customer Service about documentation problems 1 Go to https www paypal com Click Help in the upper left corner of the page 2 3 Click Contact Us in the lower left of the page 4 Choose Help by Email 5 Complete the form Revision History Revision history for PayPal Order Management Integration Guide TABLE P 1 Revision History Date Description October 2006 Details about the Downloadable Dispute Report Minor additions and corrections to some variables in Appendix A July 2006 Minor correction to values of payment status IPN variable May 2006 Description of the programmatically retrievable Disput Report Additional IPN variable values for txn type merch pmt for the Website Payments Pro monthly fee and adjustment for a resolved dispute requiring a chargeback October 2006 Adaptation to specifics for Germany Order Management Integration Guide October 2006 13 Preface Revision History 14 October 2006 Order Management Integration Guide Introduction PayPal offers four payment notification methods for backend integration e Email e Reporting Tools e Instant Payment Notification IPN e Payment Data
22. in days weeks months or years Amount of payment for trial period 1 for USD payments otherwise blank optional Amount of payment for trial period 2 for USD payments otherwise blank optional Amount of payment for regular subscription period for USD payments otherwise blank Amount of payment for trial period 1 regardless of currency optional Amount of payment for trial period 2 regardless of currency optional October 2006 Order Management Integration Guide IPN and PDT Variables EN Mass Payment TABLE A 8 Subscriptions Variables Possible Character Variable Values Description Limit mc amount3 Amount of payment for regular subscription period regardless of currency mc currency Seetable of For non payment subscriptions IPNs i e txn_type signup supported cancel failed eot or modify this is the currency of the currencies subscription For payment IPNs it is the currency of the payment i e txn type subscr_payment recurring Indicates whether regular rate recurs 1 is yes blank is no reattempt Indicates whether reattempts should occur upon payment failures 1 is yes blank is no retry_at Date PayPal will retry a failed subscription payment recur_times The number of payment installments that will occur at the regular rate username optional Username generated by PayPal and given to 64 subscriber to access the subscription password optional Password generated by PayPal an
23. not guarantee that the features described in this document will be announced or made available to anyone in the future Contents Chapter Preface 1 This Document ak sa se ERG LX Ame gm ae ee ew ae ae 11 Intended Audience a 11 Organization of This Document 11 Notational Conventions 12 Documentation Problems 13 Revision History o 13 Chapter 1 c RO Emallzos pino CCELI c 15 Reporting dr ok her der 15 Differences between Instant Payment Notification IPN and Payment Data Transfer PDT 16 SSL Not 1 17 PayPal Supported Transactional Currencies 17 Chapter 2 Payment Data Transfer 19 How PDT Works 19 Enabling Payment Data Transfer 23 Getting and Using the Identity Token 24 PDT Notification Synch 25 Constructing the POST rresia daaa 25 PayPal Response POST 26 PDT and Auto Return Messaging to 26 Preventing Fraud a 27 Code Samples sacda a uon a a
24. the program that will process the IPN posts 6 Click Save notify url Alternatively you can activate IPN by including the notify url variable in your PayPal button HTML This field specifies the URL of a program that can process the IPN For more details see IPN Notification Validation Preventing Fraud on page 31 Setting Up an IPN Processing Program The data sent to you by IPN is in the form of HTML FORM name value pairs At a minimum your program must process these pairs What other processing might be required depends on your order management needs what kinds of database you use and other factors outside the scope of this guide Code samples for the following development environments are available on the PayPal website at http www paypal com de cgi bin webscr cmd p xcl rec ipn code outside e ASP Net C ASP VBScript e ColdFusion e Java JSP e Perl e PHP IPN Notification Validation Preventing Fraud 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 IMPORTANT If you do not use Encrypted Website Payments EWP or shared secret validation you must check the price transaction ID PayPal receiver email address and other data sent to you by IPN to ensure that they are correct By examining these the data you can be sure that
25. 006 Order Management Integration Guide IPN and PDT Variables Website Payments Standard and Refund Information TABLE 4 IPN and PDT Variables Website Payments Standard and Refund Information Variable Possible Character Name Values Description Length payment_ Canceled_ The status of the payment status Reversal Canceled_Reversal A reversal has been canceled For Completed example you won a dispute with the customer and the funds for Denied the transaction that was reversed have been returned to you Expired Completed The payment has been completed and the funds Failed have been added successfully to your account balance Pending Denied You denied the payment This happens only if the 5 payment was previously pending because of possible reasons Processed described for the PendingReason element Refunded P T Expired This authorization has expired and cannot be Reversed captured Voided Failed The payment has failed This happens only if the payment was made from your customer s bank account Pending The payment is pending See pending reason for more information Refunded You refunded the payment Reversed A payment was reversed due to a chargeback or other type of reversal The funds have been removed from your account balance and returned to the buyer The reason for the reversal is specified in the ReasonCode element Processed A payment has been accepted Voided This authorization has been voided paym
26. 2 Subscriptions Variables 64 IPN Variables with Each Subscription Event 65 Dispute Notification 68 PDT Specific Variables 69 Downloadable History Log Columns and Values 71 Country Codes 79 October 2006 EN List of Tables 8 October 2006 Order Management Integration Guide Figure 3 1 Figure 4 1 Figure 4 2 Figure 4 3 Figure 4 4 Figure 4 5 Order Management Integration Guide List of Figures How IPN Works Three General Steps The History Page Download My History Customize My History Download Gross Fee and Net Amount Calculations from History Log Dispute Report October 2006 30 39 42 44 46 47 m List of Figures 10 October 2006 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 December 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 Organization of This Document Chapter 1 Introduction
27. 8 October 2006 Order Management Integration Guide 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 Norte 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 For more information about Auto Return see the PayPal Website Payments Standard Integration Guide How PDT 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 Wooden Widgets Rubber Widgets Aluminum Widgets The surprisingly compact Widget 019983763 is a powerful Steel Widgets no compromise solution for Outdoor Widgets widget professionals who are idas frequently on the road and rarely in Widget 019983763 Indoor Widgets T the office but who never want to be AAE a without the speed and power of Plastic Widgets an automotive widget It slices dices and it will even make bread Titanium Widgets Sale Price 142 50 Global Industries Inc All rights reserved 2003 Order Management Integration Guide October 2006 19 Payment Data Transfer How PDT Works Step 2 Bob is taken t
28. D Payment Type Counterparty Status Address Status Description Gross amount of transaction Fee if applicable for transaction Net amount of transaction Note for transaction as entered by counterparty Email address of transaction sender Email address of transaction recipient PayPal generated unique transaction ID Payment type used for transaction eCheck Instant PayPal Funds Account status of buyer International Unverified International Verified Unverified Verified Status of counterparty s Shipping Address Confirmed Non confirmed Format signed decimal signed decimal signed decimal alphanumeric 2000 character limit alphanumeric 128 character limit alphanumeric 128 character limit alphanumeric 17 character limit alphanumeric 27 character limit alphanumeric 27 character limit alphanumeric 14 character limit Payment Button Variable amount business Related IPN Variable payment_ gross settle_ amount amount 1 amount 2 amount 3 payment fee mc fee payer email receiver email txn id payment typ e payer statu S address status 74 October 2006 Order Management Integration Guide Downloadable History Log Columns and Values TABLE 1 Downloadable History Log Columns and Values Payment Button Related IPN Column Heading Description Format Variable Variable Item Title Specified by buy
29. E JO KZ KI Country KOREA REPUBLIC OF KUWAIT KYRGYZSTAN LAO PEOPLE S DEMO CRATIC REPUBLIC LATVIA LEBANON LESOTHO LIBERIA LIBYAN ARAB JAMA HIRIYA LIECHTENSTEIN LITHUANIA LUXEMBOURG MACAO MACEDONIA THE FORMER YUGOSLAV REPUBLIC OF MADAGASCAR MALAWI MALAYSIA MALDIVES MALI MALTA MARSHALL ISLANDS MARTINIQUE MAURITANIA MAURITIUS MAYOTTE MEXICO Code KR KW KG LA LV LB LS LR LY LI LT LU MO MK MG MW MY MV ML MT MH MQ MR MU YT MX mm Country Codes 82 Country MICRONESIA FEDER ATED STATES OF MOLDOVA REPUBLIC OF MONACO MONGOLIA MONTSERRAT MOROCCO MOZAMBIQUE MYANMAR NAMIBIA NAURU NEPAL NETHERLANDS NETHERLANDS ANTI LLES NEW CALEDONIA NEW ZEALAND NICARAGUA NIGER NIGERIA NIUE NORFOLK ISLAND NORTHERN MARIANA ISLANDS NORWAY OMAN PAKISTAN Code MD MC MN MS MA MZ MM NA NR NP NL AN NC NZ NI NE NG NU NF MP NO OM PK Country PALAU PALESTINIAN TERRI TORY OCCUPIED PANAMA PAPUA NEW GUINEA PARAGUAY PERU PHILIPPINES PITCAIRN POLAND PORTUGAL PUERTO RICO QATAR REUNION ROMANIA RUSSIAN FEDERATION RWANDA SAINT HELENA SAINT KITTS AND NEVIS SAINT LUCIA SAINT PIERRE AND MIQUELON SAINT VINCENT AND THE GRENADINES SAMOA SAN MARINO Code PW PS PA PG PY PE PH PN PL PR QA RE RO RU RW SH LC PM WS SM Country SAO TOME AND PRINC IPE
30. EUER Order Management Integration Guide October 2006 21 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 You Made A Payment Your payment for 162 50 USD has been completed You are now being redirected to Widget Warehouse If you are not redirected within 10 seconds click here 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 Included in the HTTP post is the identity token that was given to the Widget Warehouse when PDT was enabled For more information about the PDT identity token see Getting and Using the Identity Token on page 24 For more information about the HTTP POST see PDT Notification Synch on page 25 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 22 October 2006 Order Management Integration Guide Payment Data Transfer Enabling Payment Data Transfer For example
31. History entry is updated for example in the case of a refund the Net Amount column indicates the current net value of the transaction on a separate line item FIGURE 4 4 Gross Fee and Net Amount Calculations from History Log ug 29 2005 Status Details Action Gross Fee Net Amount Pending Details Remind Cancel 1 00 EUR 0 00 EUR 1 00 EUR Completed Details 0 50 USD 0 00 USD 0 50 USD nal Interiors Unclaimed Details 1 00 CAD 0 00 CAD 1 00 CAD Completed Details 1 00 USD 0 00 USD 1 00 USD Unclaimed Details 1 00 CAD 0 00 CAD 1 00 CAD Dispute Report 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 e Complaint A buyer has used the PayPal Resolution Center to register a claim about a payment to a merchant Note After notification about a complaint claim merchants must log in to PayPal to use the Resolution Center to respond to the case e Chargeback A buyer has filed a complaint with a credit card company that has resulted in a chargeback The credit card company notifies PayPal about the reason for the chargeback After investigating the case PayPal notifies the merchant of any action required Note The IPN messages for chargebacks resulting from a complaint are asynchronous the IPN message for the chargeback can be sent to the merchant before the IPN
32. IPNs such as signup cancel modify failed and eot nc currency is the currency of the subscription rather than the currency of the payment Norte The variables nc gross and mc fee will not be added to IPNs with txn type subscr signup subscr cancel subscr modify subscr failed or subscr eot October 2006 Order Management Integration Guide Instant Payment Notification IPN mM Using IPN with Multiple Currencies mc currency This variable reflects the currency of mc gross mc fee payment gross and payment fee amounts Possible values are detailed in PayPal Supported Transactional Currencies on page 17 payment gross and payment fee These variables reflect the amount received and corresponding fee of US Dollar USD payments If the amount received and fee deducted are in a currency other than USD the variables will still appear in your IPN but will have no values in them Examples of Multi currency IPN Variables Example 1 If a user with a EUR balance receives a 100 EUR payment the following variables will be used for the payment e mc gross and mc_fee have values e payment gross and payment fee are blank EXAMPLE 3 1 Multi currency IPN EUR Payment payment status Completed payment gross payment fee mc gross 100 mc fee 3 00 mc currency EUR Example 2 f a user with a USD balance receives a 100 USD payment the following variables will be used for the payment e mc gross payme
33. Once you have completed the above checks you can update your database based on the information provided If you receive an INVALID response you should investigate In some cases this response is caused by an IPN error possibly from a change in the IPN format To determine if it is an IPN error first examine your code If you need further assistance go to http www paypal com wf click the Seller Tools topic and click Instant Payment Notification IPN Using IPN with Multiple Currencies With multiple currencies you can accept payments in any of the PayPal supported currencies see PayPal Supported Transactional Currencies on page 17 As a result your IPNs will then include information about the currency of the payment The following overview explains how IPN interacts with multiple currencies Note If you are using one of PayPal s Website Payments solutions e g PayPal Shopping Cart and would like to be paid in a currency other than Euro you will need to set up your buttons for your currency of choice mc gross and mc fee These variables reflect the amount received and corresponding fee of your payments In order to see those variables IPN has to use gross variable mc gross Full amount of payment received before transaction fee mc fee Transaction fee associated with the payment NoTE mc fee is not always present in IPNs such as when a payment is pending For subscription
34. PayPal Order Management Integration Guide For Professional Use Only Currently only available in English A usage Professional Uniquement Disponible en Anglais uniquement pour l instant Last Updated October 2006 PayPal Order Management Integration Guide Document Number 100009 en_US 200608 2006 PayPal Inc All rights reserved PayPal and the PayPal logo are registered trademarks of PayPal Inc Other trademarks and brands are the property of their respective owners The information in this document belongs to PayPal Inc It may not be used reproduced or disclosed without the written approval of PayPal Inc PayPa PayPa Notice PayPa Europe Ltd is authorised and regulated by the Financial Services Authority in the United Kingdom as an electronic money institution FSA Register Number 226056 of non liability Inc is providing the information in this document to you iAS ISi with all faults PayPal Inc makes no warranties of any kind whether express implied or statutory with respect to the information contained herein PayPal Inc assumes no liability for damages whether direct or indirect caused by errors or omi ssions or resulting from the use of this document or the information contained in this document or resulting from the application or use of the product or service described herein PayPal Inc reserves the right to make changes to any information herein without further notice PayPa Inc does
35. ST must be sent to https www paypal com cgi bin webscr 2 You must include the cmd variable with the value notify synch cmd notify synch 3 You must include the transaction token in the variable tx and the value of the transaction token received via PayPal s GET tx value of transaction token 4 You must post your identity token using the variable at and the value of your PDT identity token at your identity token Order Management Integration Guide October 2006 25 26 Payment Data Transfer PDT Notification Synch For information about the identity token see Getting and Using the Identity Token on page 24 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 Example successful response SUCCESS first_name Jane Doe last_name Smith payment_status Completed payer email janedoesmith 40hotmail com payment gross 3 99 mc currency USD custom For the purchase of the rare book Green Eggs 26 Ham If the response is FAIL PayPal recommends making sure that e The Transaction token is not bad e The ID token is not bad e The tokens have not expired PDT an
36. _amount 145 5 settle_currency EUR exchange_rate 1 5 If the payment is accepted into a balance of the same currency EXAMPLE 3 6 Pending Accept to Currency Balance payment_status Completed payment_gross payment_fee mc_gross 100 mc_fee 3 00 October 2006 Order Management Integration Guide Instant Payment Notification IPN Using IPN with Multiple Currencies mc currency GBP If the payment is denied EXAMPLE 3 7 Pending Denied payment status Denied payment gross mc gross 100 mc currency GBP NOTE If a user receives a payment into a currency balance and later converts this amount into another currency balance the corresponding currency conversion transaction has no IPN Order Management Integration Guide October 2006 37 a Instant Payment Notification IPN Using IPN with Multiple Currencies 38 October 2006 Order Management Integration Guide Transaction History and Reporting Tools With transaction history and reporting tools you can access monthly account statements search specific time periods for transaction records or customer disputes and download these search results to your local computer To access these features 1 Log in to your PayPal Business or Premier account 2 Click the History subtab The History page is shown in Figure 4 1 The History Page FIGURE 4 1 The History Page PayPal Log Out PayPalHome Help Security Center Search
37. alance Order Management Integration Guide October 2006 43 Transaction History and Reporting Tools Download My History FIGURE 4 3 Customize My History Download My Account Send Money Request Money Merchant Services Auction Tools Products amp Services Overview AddFunds Withdraw History Resolution Center Profile Customize My History Download Check the boxes next to the fields you want ta download All checked fields will be included in your downloadable lag Default Fields Date Time Timezone Name Type Status Currency Gross Fee Net From Email Address To Email Address Transaction ID Reference Transaction ID Receipt ID Balance PayPal Website Payments M Item ID Iv Item Title M Invoice Number M Custom Number Iv Shipping Amount M Insurance Amount Single Column Shipping Address Address will be displayed in a single column M Multi Column Shipping Address Address will be displayed in separate columns New M Counter Party Status Verified vs Unverified M Address Status Confirmed vs Unconfirmed MW Sales Tax Option Names and Values Auction Payments Item ID Item Title Shipping amp mount Insurance Amount Auction Site Buyer ID Item URL Iv Closing Date Single Column Shipping Address Address will be displayed in a single column Multi Column Shipping Address Address will be displayed in separate columns News Iv Counter Party Status Verified vs Unverified M Addr
38. ame Values Description Length mc Transaction This is the combined total of shipping and shipping2 shipping x specific for WebsitePayments variables where x is the shopping cart detail multiple item number The shippingx variable is only shown when the currencies merchant applies a shipping amount for a specific item Because profile shipping might apply the sum of shippingx might not be equal to shipping num cart _ If this is a PayPal Shopping Cart transaction number of items in items cart option PayPal appends the number of the item where x represents the 64 namel number of the shopping cart detail item e g option namel option name2 option PayPal appends the number of the item where x represents the 64 name2 number of the shopping cart detail item e g option name2 option name2 option PayPal appends the number of the item e g 200 selectionl option selectionl option selection2 where x represents the number of the shopping cart detail item option_ PayPal appends the number of the item where x represents the 200 selection2_ number of the shopping cart detail item e g option selectionl option selection2 parent txn In the case of a refund reversal or canceled reversal this 19 id variable contains the txn_id of the original transaction while txn id contains a new ID for the new transaction payment Time Date stamp generated by PayPal in the following format 28 date HH MM SS DD Mmm YY YYYY PST October 2
39. amel 54 56 option name2 54 56 option selectionl 54 option selectionl x 56 option selection2 55 option selection2 x 56 other 58 P parent txn id 56 password 65 payer business name 53 payer email 53 payer id 53 payer status 53 payment tatus 57 payment date 56 62 payment fee 60 payment fee x 62 payment gross 61 payment gross x 62 payment status 51 62 payment type 57 October 2006 Order Management Integration Guide PayPal supported currencies 17 Pending 55 57 pending reason 58 period 64 period2 64 period3 64 PLN 17 Polish Zloty 17 Pound Sterling 17 Processed 57 Q qif file format 43 quantity 53 QuickBooks 43 Quicken 43 R reason_code 59 63 68 ReasonCode 57 reattempt 65 receiver email x 63 receiver email 53 54 receiver id 54 recur times 65 recurring 65 Refunded 57 remaining settle 59 residence country 53 retry at 65 Reversed 57 S SEK 17 send money 59 settle amount 61 settle currency 61 SGD 17 shipping 59 Singapore Dollar 17 special 69 st 69 status x 63 subscr cancel 64 Order Management Integration Guide subscr date 64 subscr effective 64 subscr eot 64 subscr failed 64 subscr id 65 subscr modify 64 subscr payment 64 subscr signup 64 Swedish Krona 17 Swiss Franc 17 T tax 55 50 test ipn 51 transaction search online 40 transaction entity 59 tx 69 txn id 59 68 txn type 59 63 64 68 U U S Dollar 17 unauthorized 69 unilateral 58
40. bscr cmd p xcl rec pdt code There are code samples for the following development environments ASP VBScript e ColdFusion e PERL e PHP Order Management Integration Guide October 2006 27 Payment Data Transfer Code Samples 28 October 2006 Order Management Integration Guide 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 This chapter details IPN in the following sections About IPN on page 29 Setting Up IPN on page 30 IPN Notification Validation Preventing Fraud on page 31 Using IPN with Multiple Currencies on page 34 About IPN Instant Payment Notification consists of three parts 1 2 A customer pays you PayPal POSTs FORM variables to a URL you specify that runs a program to process the variables You validate the notification Order Management Integration Guide October 2006 29 mm Instant Payment Notification IPN Setting Up IPN FIGURE 3 1 How IPN Works Three General Steps Customer Browser lt FORM METHOD POST ACTION https www paypal com cgi bin webscr gt PayPal NS 4 IPN post to your program lt Notification Validation 1 A customer payment or a refund triggers IPN This payment can be via Website Payme
41. d Auto Return Messaging to Buyer When Auto Return you must display a message on the page displayed by the Return URL that helps the buyer understand that the payment has been made that the transaction has been completed and that payment transaction details will be emailed to the buyer You can display to your customer whatever payment details you feel are appropriate however PayPal recommends including the following e Item name e Amount paid e Payer email e Shipping address If you are using PDT to determine when to fulfill an order automatically confirm that the payment_status is Completed since the buyer could use methods such as EFT that do not immediately clear For a list of PDT variables see Appendix A IPN and PDT Variables October 2006 Order Management Integration Guide Payment Data Transfer 8 Preventing Fraud Preventing Fraud In order to prevent fraud PayPal recommends that your programs verify the following e txn idis not a duplicate to prevent someone from reusing an old completed transaction e receiver email is an email address registered in your PayPal account to prevent the payment from being sent to a fraudulent account e Other transaction details such as the item number and price to confirm that the price has not been changed Code Samples PayPal has made available code samples that you can use to set up PDT These samples are available at https www paypal com us cgi bin we
42. d given to 24 subscriber to access the subscription password will be encrypted subscr_id ID generated by PayPal for the subscriber 19 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 when a payment or refund occurs For all other events the pertinent variable is txn_type TABLE A 9 IPN Variables with Each Subscription Event Payment Payment Multi Variable Signup Cancel Modify USD Currency Refund Failed EOT Basic Information business X X X X X X X receiver email X X X X X X X receiver id X X item name X X X X X X X Order Management Integration Guide October 2006 65 66 IPN and PDT Variables Mass Payment TABLE A 9 IPN Variables with Each Subscription Event Payment Payment Multi Variable Signup Cancel Modify USD Currency Refund Failed item_number X X X X X X X Advanced and Custom Information invoice X X X X X X X custom X X X X X X X option namel X X X X X X X option selecti X X X X X X X oni option name2 X X X X X X X option selecti X X X X X X X on2 Transaction Information payment status X X X pending reason X X reason code X X payment date X X txn id X X parent txn id X X txn type subscr _ subscr subscr subscr payment subscr
43. e of a Transaction Status Every transaction in your History Log shows the transaction a status at the time the data were downloaded and its corresponding impact on your balance Various types of transaction statuses and scenarios can have a negative positive or neutral balance impact These statuses include e Pending e Held e Completed e Denied e Cancelled e Reversed For a complete list of possible transaction statuses see Status on page 73 Pending to Completed or Cancelled When a pending payment such as an EFT completes after the he buyer has sent the money from his bank the transaction status changes from Pending to Completed Status of Disputed Transactions Transactions with a Placed status for temporary holds usually involve a customer dispute Order Management Integration Guide October 2006 45 46 Transaction History and Reporting Tools Dispute Report If you are found in favor in a dispute the transaction will be updated with a new line item to indicate a Credit However if the opposite is true the Balance Impact column will not change from the Debit status for that transaction You can generate a dispute report that correlates the transaction to the customer and the reason for the dispute For more information see Dispute Report on page 46 Net Amount Column The Net Amount of a transaction can aid in faster reconciliation In most cases the Net Amount is the Gross minus Fee When a
44. eans that your funds were not sent and the Mass Payment was not initiated This may have been caused by lack of funds Processed Your Mass Payment has been processed and all payments have been sent October 2006 Order Management Integration Guide IPN and PDT Variables EN Mass Payment TABLE A 7 IPN and PDT Variables Mass Payment Variable Possible Character Name Values Description Length reason code 1001 This variable is only set if status Failed 1003 1001 Invalid UserID 1004 1003 Country of Residence check failure 1004 Country of Funding Source check failure receiver_ For Mass Payments the primary email address of the payment 127 email_x recipient where x is the record number of the mass pay item status_x Completed For Mass Payments the status of the payment where x is the Failed record number Reversed Completed The payment has been processed regardless of Uneladined whether this was originally a unilateral payment Failed The payment failed because of insufficient PayPal balance Reversed This is for unilateral payments that were not claimed after 30 days and have been returned to the sender Or the funds have been returned because the Receiver s account was locked Unclaimed This is for unilateral payments that are unclaimed txn_type masspay This payment was sent via Mass Payment unique_id_x For Mass Payments the unique ID from input where x is the 13 record number This allows the merchant
45. ebit Card Credit Update to eCheck Received Update to Payment Received Update to Payment Sent continued Payment Button Related IPN Variable Variable txn_type October 2006 Order Management Integration Guide Downloadable History Log Columns and Values TABLE 1 Downloadable History Log Columns and Values Payment Button Related IPN Column Heading Description Format Variable Variable Type continued Update to Reversal Update to Web Accept Payment Received Virtual Debit Card Authorization Virtual Debit Card Credit Received Virtual Debit Card Purchase Virtual Debt Card Credit Received Web Accept Payment Received Web Accept Payment Sent Withdraw Funds to a Bank Account Status Status of transaction at time of alphanumeric payment _ download 10 character status Canceled limit pending_ Cleared reason Completed Denied Expired Failed Pending Refunded Returned Reversed Unclaimed Uncleared Subject Subject of transaction as entered by alphanumeric counterparty 256 character limit Currency Currency of transaction alphanumeric currency mc currency three character code settle_ limit currency exchange_ rate mc_gross Order Management Integration Guide October 2006 73 a Downloadable History Log Columns and Values TABLE B 1 Downloadable History Log Columns and Values Column Heading Gross Fee Net Note From Email Address To Email Address Transaction I
46. ed when the customer provides 128 name a Gift Address address_ State of customer s address 40 state address_ confirmed Customer provided a confirmed address status unconfirmed Customer provided an unconfirmed address address_ Customer s street address 200 street address_zip Zip code of customer s address 20 first_name Customer s first name 64 October 2006 Order Management Integration Guide IPN and PDT Variables Basic Information TABLE A 1 PN and PDT Variables Buyer Information Variable Possible Character Name Values Description Length last_name Customer s last name 64 payer_ Customer s company name if customer represents a business 127 business_ name payer_email Customer s primary email address Use this email to provide 127 any credits payer_id Unique customer ID 13 payer_ verified Customer has a Verified PayPal account status unverified Customer has an Unverified PayPal account residence_ Two character ISO 3166 country code 2 country Basic Information TABLE 2 IPN and PDT Variables Basic Information Variable Possible Character Name Values Description Length business Email address or account ID of the payment recipient that is 127 the merchant Equivalent to the values of receiver_email if payment is sent to primary account and business set in the Website Payment HTML NOTE The value of this variable is normalized to lowercase characters item_name Item name
47. ent_ echeck echeck This payment was funded with an eCheck or EFT type instant instant This payment was funded with PayPal balance ELV giropay credit card or Instant Transfer Order Management Integration Guide October 2006 57 IPN and PDT Variables Website Payments Standard and Refund Information TABLE 4 IPN and PDT Variables Website Payments Standard and Refund Information Variable Possible Character Name Values Description Length pending_ address This variable is set only if payment_status Pending reason authorization address The payment is pending because your customer did echeck not include a confirmed shipping address and your Payment inti Receiving Preferences is set yo allow you to manually accept or deny each of these payments To change your preference go to multi 5 the Preferences section of your Profile currency authorization You set lt PaymentAction gt unilateral Authorization lt PaymentAction gt on upgrade SetExpressCheckoutRequest and have not yet captured verify funds other echeck The payment is pending because it was made by mEFT and PayPal hasn t received the funds yet or an eCheck that has not yet cleared intl The payment is pending because you hold a non U S account and do not have a withdrawal mechanism You must manually accept or deny this payment from your Account Overview multi currency You do not have a balance in the currency sent and you do not have your Pay
48. er in the website alphanumeric item name item name field 128 character e Auction Item Title limit Or by seller in any of the following button creation fields e PayPal Shopping Cart Item Name e Buy Now Item Name e Donations Item Name e Subscriptions Name Item ID Specified by buyer in the website alphanumeric item number item number field 256 character e Auction Item Number limit Or by seller in any of the following button creation fields e PayPal Shopping Cart Item Number e Buy Now ID Number e Donations ID Number e Subscription Reference Number Shipping Amount Specified by buyer in the website unsigned shipping field decimal shipping2 e eBay Auction Shipping amount handling Or by seller in any of the following button creation fields e PayPal Shopping Cart Shipping amount e Buy Now Shipping amount Insurance Amount Specified by buyer in the website unsigned field decimal e eBay Auction Insurance amount Sales Tax Sales Tax Amount specified in unsigned tax seller s button creation process and decimal Profile preferences Option 1 Name Specified by seller in any of the alphanumeric option name following button creation fields 60 character 1 e PayPal Shopping Cart Option 1 limit Name e Buy Now Option 1 Name e Subscription Option 1 Name Order Management Integration Guide October 2006 75 a Downloadable History Log Columns and Values TABLE B 1 Downloadable History Log Columns and Values Payment Bu
49. es and fields For example Abst ractResponseType 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 For example The PayPal system uses a method POST request to return IPN status variables related to subscriptions such as txn_type User interface names such as window names or menu selections For example On the Profile page click Email to confirm your email address 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 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 XXXXXX Hypertext link to a page in the current document or to another document in the set Hypertext link to a URL or that initiates a web action such as sending mail October 2006 Order Management Integration Guide Preface Documentation Problems Documentation Problems If you discover any errors in or
50. esolution Center Profile Monthly Account Statements Back to Profile Summary PayPal s Monthly Account Statements allow you to view and print a concise monthly summary of your account s activity Id you like to receive Monthly Account Statements Yes No Cancel 3 Click Save Online History Searching The History page gives you many options for searching the transaction records viewable online There are two types of searches basic and advanced e With basic search you specify the date range and type of activity you re interested in e With advanced search you specify the date range and a pattern you want to find in certain fields of the transaction records Basic Search Time Periods You have two ways to narrow the search 1 You can select a pre determined date range The Past Day The Past Week The Past Month The Past Year 2 You can select an exact From and To range of day month and year 40 October 2006 Order Management Integration Guide Transaction History and Reporting Tools Online History Searching IMPORTANT The length of time of the date range affects how quickly you see the results The longer the time the slower the search For the speediest results try to make the range as narrow as possible Basic Search Activity Types The default set of transactions also called activities is All Activity Simple View The selectable activity types are listed in Table 4 1
51. ess Status Confirmed vs Unconfirmed M Sales Tax Other Fields Subject Note E Subscription Number Paymen pe Balance Impact Any transaction that affects account balance October 2006 Order Management Integration Guide Transaction History and Reporting Tools Download My History Transaction Reconciliation with the Balance Impact Column The Balance Impact column shows the word Credit for a positive effect or the word Debit for a negative effect on your PayPal account balance Credit When you receive an instant payment or credit card transaction the Balance Impact column indicates a credit Other possible credits to your account are refunds reversals and payments sent but never claimed In some cases a credit line item can update a debit for a transaction For example if you send a payment initially indicated as a debit but it is denied by the recipient a new line item for that transaction will indicate a credit Debit Debits are transactions that reduce your available balance For example refunded transactions are recorded as a debit in the Balance Impact column and as completed in the Status column Memo Entries The Balance Impact column can display a Memo entry for transactions that do not affect your balance such as unclaimed or uncleared transactions These kinds of transactions have no impact on your balance since neither transaction ever becomes a completed transaction Lifecycl
52. f the date the case was created or the current status of the case Use this report as a starting point against which you will read future DDR reports Note If you need to regenerate the first report contact your PayPal Account Manager and ask them to generate a first day DDR report for you Subsequent Daily DDR Reports Following the first DDR report reports are generated daily and contain information about dispute activity for your account in the past 24 hours or since the last report was generated including e New cases created e Cases that were modified including cases that were closed Frequency Archiving The DDR is generated every day based on activity for the previous day Days with no activity will generate an empty report PayPal will maintain DDR reports for seven days after which the report will not longer be available Report Set Up To use the DDR you must 1 Sign up for the report through your PayPal Account Manager 2 Create a unique user to download the report 3 Write code to download the report from a PayPal server Step 1 Sign up for the report via PayPal Account Management Contact your PayPal Account Manager to sign up for the Downloadable Dispute Report Step 2 Create a Unique User on PayPal to Download the Report To use the DDR you must use PayPal s Multi User Access feature to create a unique user for downloading reports 1 Login to your PayPal account 2 Select the Profile subtab
53. hod for validating your receipt of an IPN is to post back to PayPal the exact variables and values you received in the IPN Constructing the POST Here are the guidelines for constructing the IPN HTTPS POST to PayPal for notification validation NOTE You can implement IPN without SSL but PayPal recommends against doing so 1 Your POST must be sent to https www paypal com cgi bin webscr 2 You must include the variable cmd with the value _notify validate cmd notify validate 3 You must post all the form variables you received exactly as you received them 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 Order Management Integration Guide October 2006 33 34 Instant Payment Notification IPN Using IPN with Multiple Currencies 5 Check that the payment_status is Completed 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 After you have checked the payment_status and txn_id make sure the receiver_email is an email address registered in your PayPal account Check that the price mc gross and currency mc currency are correct for the item item name or item number Check the the shared secret returned to you is correct
54. idden NAME uname VALUE queuealias2 gt lt INPUT TYPE hidden NAME pword VALUE 22222222 gt lt INPUT TYPE image VALUE Submit gt lt FORM gt View the Report You will receive an email when the report is ready This email contains a link to the report which can you access via a browser You can also use the email as a trigger for your code to programmatically access the report Order Management Integration Guide October 2006 49 Transaction History and Reporting Tools Dispute Report 50 October 2006 Order Management Integration Guide 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 In addition values posted by IPN are URL encoded For example a colon in http is encoded as 3A in the IPN post http 3A About These Tables of Variables The tables in this appendix group IPN variables by different characteristics test_ipn Variable in Sandbox on page 51 IPN Variables in All Posts on page 52 Buyer Information on page 52 Basic Information on page 53 Advanced and Custom Information on page 54 Website Payments Standard and Refund Information on page 55 Currency and Currency Exchange on page 60 Auctions on page 61 Mass Payment on page 62 Dispute
55. imbursement non receipt Buyer claims that he did not receive goods or service duplicate Buyer claims that a possible duplicate payment was made to the merchant merchandise Buyer claims that the received merchandise is unsatisfactory defective or damaged special Some other reason Usually special indicates a credit card processing error for which the merchant is not responsible and for which no debit to the merchant will result PayPal must review the documentation from the credit card company to determine the nature of the dispute and possibly contact the merchant to resolve it PDT Specific Variables The following variables apply only to PDT TABLE A 11 PDT Specific Variables Variable Description amt Amount of the transaction Currency code cm Custom message st Transaction status tx Transaction ID PDT token Order Management Integration Guide October 2006 69 EN IPN and PDT Variables PDT Specific Variables 70 October 2006 Order Management Integration Guide Downloadable History Log Columns and Values TABLE B 1 Downloadable History Log Columns and Values Column Heading Description Date Time Timezone Name Date transaction was initiated according to PayPal system time US Pacific time zone Log sorted in reverse chronological order by Date most recent first Time transaction was initiated according to PayPal system time US Pacific time zone The time zone used f
56. in the account in a 24 hour period A super set of data contained in Settlement Report including buyer and auction data Order Report ODR List all orders created in a 24 hr period with the order ID Only appropriate for those merchants using the order functionality on their website Dispute Resolution Report DRR List all cases that changed in status or were created in a 24 hr period Allows a merchant to reconcile cases against money moving transactions e History Log View an online record of your received and sent payments e 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 cgi bin webscr cmdzp xcl rec reports intro outside Differences between Instant Payment Notification IPN and Payment Data Transfer PDT PDT s primary function is to display payment transaction details to buyers when they are automatically redirected back to your site upon payment completion however there are cases where you will not receive notification of all transactions such as with pending transactions refunds and reversals For these reasons or if you are using this data to fulfill orders PayPal strongly recommends that you also enable Instant Payment Notification IPN Both IPN and PDT send back the same data however there are several important differences PDT e Requ
57. ion Guide Payment Data Transfer PDT Notification Synch You will need to pass this identity token along with the transaction token to PayPal in order to receive information that confirms that a payment is complete Payment Data Transfer optional Payment Data Transfer allows you to receive notification of successful payments as they are made The use of Payment Data Transfer depends on your system configuration and your Return URL Please note that in order to use Payment Data Transfer you must turn on Auto Return Payment Data On Transfer C off Identity Token imeSWn6 ZISil9BdnDY4g570zrgYomzimewyXqrwb445qFj1h8eiR3cUFhe For security the identity token is not sent to you however once you have enabled PDT it permanently appears below the Payment Data Transfer On Off radio buttons on the Website Payments Preferences page PDT Notification Synch After you have activated PDT every time a buyer makes a website payment and is redirected to your return URL a transaction token is sent via a FORM GET variable to this return URL To properly use PDT and display transaction details to your customer you should read the transaction token from the variable tx and retrieve transaction details from PayPal by constructing an HTTPS POST to PayPal This is called notification synch or synchronization Constructing the POST Here are the guidelines for constructing the PDT HTTPS POST to PayPal for notification synch 1 Your PO
58. ion Smart Logos Order Management Integration Guide October 2006 59 IPN and PDT Variables Currency and Currency Exchange Currency and Currency Exchange TABLE A 5 PNand PDT Variables Currency and Currency Exchange Information Variable Possible Character Name Values Description Length exchange_ Exchange rate used if a currency conversion occurred rate mc currency Three For payment IPNs this is the currency of the payment For non mc fee mc gross mc handling mc_shipping payment_fee character currency code See table of supported currencies Transaction specific for USD payments only payment subscription IPNs this is the currency of the subscription Transaction fee associated with the payment mc_gross minus mc fee equals the amount deposited into the receiver email account Equivalent to payment fee for USD payments If this amount is negative it signifies a refund or reversal and either of those payment statuses can be for the full or partial amount of the original transaction fee Full amount of the customer s payment before transaction fee is subtracted Equivalent to payment gross for USD payments If this amount is negative it signifies a refund or reversal and either of those payment statuses can be for the full or partial amount of the original transaction Total handling amount associated with the transaction If this is a shopping cart transaction see Table A 4 IPN and
59. ion_multi_item 61 AUD 17 Australian Dollar 17 auth_amount 55 auth_exp 55 auth_id 55 auth_status 55 authorization 58 B Balance 41 business 53 17 Canadian Dollar 17 Canceled Reversal 57 cart 59 case_creation_date 68 case_id 68 Order Management Integration Guide case_type 68 69 chargeback 68 CHF 17 cm 69 complaint 68 Completed 55 57 currency codes 17 custom 54 Czech Koruna 17 CZK 17 D Danish Krone 17 Denied 57 DKK 17 duplicate 69 E echeck 57 58 EUR 17 Euro 17 exchange_rate 60 Expired 57 express_checkout 59 F Failed 57 first_name 52 for_auction 61 Forint 17 G GBP 17 October 2006 85 H History 39 HKD 17 Hong Kong Dollar 17 HUF 17 Hungarian Forint 17 uf file format 43 instant 57 intl 58 invoice 54 item_name 53 item_number 53 J Japanese Yen 17 JPY 17 K Koruna 17 Krona 17 Krone 17 L last_name 53 masspay_txn_id_x 62 mc amountl 64 mc amount2 64 mc amount3 65 mc currency 60 65 mc currency x 62 mc fee 60 62 mc fee x 62 mc gross 60 mc gross x 55 62 mc handling 60 mc handling x 55 mc shipping 60 86 mc shipping x 56 memo 54 merchandise 69 monthly account statements 39 multi currency 58 N Net Amount 46 New Zealand Dollar 17 new case 68 NOK 17 non receipt 68 69 Norwegian Krone 17 not as described 69 notify version 52 num cart items 56 NZD 17 O option name 1 54 option name 2 54 option n
60. ires Auto Return to be enabled e Auto Return will include an ID that can be used to query PayPal for the complete transaction details e Itis possible to miss a notification if the user closes the browser before the redirection is complete IPN e Does not require Auto Return to be enabled e Atthe end of the website payment flow PayPal POSTS the IPN data asynchronously i e not as part of the website payment flow e IPNs will also POST for EFT completions reversals and refunds 16 October 2006 Order Management Integration Guide SSL Not Required for IPN Because credit card and bank information is not transmitted in Instant Payment Notification IPN PayPal does not require Secure Sockets Layer SSL to encrypt IPN transmissions Introduction PayPal Supported Transactional Currencies PayPal Supported Transactional Currencies The following currencies are supported by PayPal for use in transactions TABLE 1 1 PayPal Supported Currencies and Currency Codes for Transactions ISO 4217 Code Currency AUD Australian Dollar CAD Canadian Dollar CHF Swiss Franc CZK Czech Koruna DKK Danish Krone EUR Euro GBP Pound Sterling HKD Hong Kong Dollar HUF Hungarian Forint JPY Japanese Yen NOK Norwegian Krone NZD New Zealand Dollar PLN Polish Zloty SEK Swedish Krona SGD Singapore Dollar USD U S Dollar Order Management Integration Guide October 2006 17 m Introduction PayPal Supported Transactional Currencies 1
61. m automatic conversion through your Payment Receiving Preferences or manual conversion through manually accepting a payment settle_ Three Currency of settle amount currency character currency code See table of supported currencies Auctions TABLE A 6 IPN and PDT Variables Auctions Variable Possible Character Name Values Description Length auction_ The customer s auction ID 64 buyer_id auction_ The auction s close date in the following format HH MM SS 28 closing_ DD Mmm YY YYYY PST date auction_ The number of items purchased in multi item auction payments multi_item It allows you to count the mc_gross or payment gross for the first IPN you receive from a multi item auction auction_multi_item since each item from the auction will generate an Instant Payment Notification showing the amount for the entire auction for_auction true This is an auction payment payments made using Pay for eBay Items or Smart Logos as well as Send Money Money Request payments with the type eBay items or Auction Goods non eBay Order Management Integration Guide October 2006 61 IPN and PDT Variables Mass Payment Mass Payment TABLE 7 IPN and PDT Variables Mass Payment Variable Possible Character Name Values Description Length masspay_ For Mass Payments a unique transaction ID generated by the 19 txn_id_x PayPal system where x is the record number of the mass pay item mc currency Transaction For Mass Payments
62. ment Receiving Preferences set to automatically convert and accept this payment You must manually accept or deny this payment unilateral The payment is pending because it was made to an email address that is not yet registered or confirmed upgrade The payment is pending because it was made via credit card and you must upgrade your account to Business or Premier status in order to receive the funds upgrade can also mean that you have reached the monthly limit for transactions on your account verify The payment is pending because you are not yet verified You must verify your account before you can accept this payment other The payment is pending for a reason other than those listed above For more information contact PayPal Customer Service October 2006 Order Management Integration Guide IPN and PDT Variables Website Payments Standard and Refund Information TABLE 4 IPN and PDT Variables Website Payments Standard and Refund Information Variable Possible Character Name Values Description Length reason code chargeback This variable is set if payment status Reversed guarantee Refunded or Cancelled Reversal buyer _ chargeback A reversal has occurred on this transaction due to complaint a chargeback by your customer refund guarantee reversal has occurred on this transaction due to other your customer triggering a money back guarantee buyer complaint A reversal has occurred on this transaction due to a
63. n tax Amount of tax charged on payment If this is a shopping cart transaction see Table A 4 IPN and PDT Variables Website Payments Standard and Refund Information on page 55 for more information Website Payments Standard and Refund Information TABLE 4 IPN and PDT Variables Website Payments Standard and Refund Information Variable Possible Character Name Values Description Length auth id Transaction Authorization identification number 19 specific auth exp Transaction Authorization expiration date and time in the following format 28 specific HH MM SS DD Mmm YY YYYY PST auth amount Transaction Authorization amount specific auth status Completed Status of authorization Pending Voided mc gross x Transaction The amount is in the currency of mc currency where x is the specific for shopping cart detail item number The sum of mc gross x multiple should total mc gross currencies mc Transaction The x is the shopping cart detail item number The handling x specific for handling cart cart wide Website Payments variable is also multiple included in the mc handling variable for this reason the sum currencies of mo handling x might not be equal to mc handling Order Management Integration Guide October 2006 55 56 IPN and PDT Variables Website Payments Standard and Refund Information TABLE 4 IPN and PDT Variables Website Payments Standard and Refund Information Variable Possible Character N
64. nt These are pass 255 through variables that are never presented to your customer invoice Passthrough variable you can use to identify your Invoice 127 Number for this purchase If omittted no variable is passed back memo Memo as entered by your customer in PayPal Website Payments 255 note field option Option I name as requested by you 64 name 1 If this is a shopping cart transaction see Table A 4 IPN and PDT Variables Website Payments Standard and Refund Information on page 55 for more information option_ Option 2 name as requested by you 64 name_2 If this is a shopping cart transaction see Table A 4 IPN and PDT Variables Website Payments Standard and Refund Information on page 55 for more information option_ Option I choice as entered by your customer 200 selectionl If this is a shopping cart transaction see Table A 4 IPN and PDT Variables Website Payments Standard and Refund Information on page 55 for more information October 2006 Order Management Integration Guide IPN and PDT Variables Website Payments Standard and Refund Information TABLE IPN and PDT Variables Advanced and Custom Information Variable Possible Character Name Values Description Length option_ Option 2 choice as entered by your customer 200 selection2 If this is a shopping cart transaction see Table A 4 IPN and PDT Variables Website Payments Standard and Refund Information on page 55 for more informatio
65. nt gross e mc fee payment fee EXAMPLE 3 2 Multi currency IPN USD Payment payment status Completed payment gross 100 payment fee 3 00 mc gross 100 mc fee 3 00 mc currency USD Order Management Integration Guide October 2006 35 36 Instant Payment Notification IPN Using IPN with Multiple Currencies 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 EUR balance who receives a payment of 100 GBP EXAMPLE 3 3 Muili currency IPN Automatic Conversion of GBP Payment payment_status Completed payment_gross payment_fee mc_gross 100 mc_fee 3 00 mc_currency GBP settle_amount 145 5 settle_currency EUR exchange_rate 1 5 Example 4 If a payment received is pending due to pending_reason multi_currency the first IPN received would not have the settle amount settle currency or exchange rate EXAMPLE 3 4 Mutli currency IPN Pending Payment payment status Pending pending reason multi currency payment gross mc gross 100 mc currency GBP The second IPN contains information about settling the payment If the payment is accepted into the account s primary currency which is EUR in the following example EXAMPLE 3 5 Pending Convert to Primary Currency payment_status Completed payment_gross payment_fee mc_gross 100 mc_fee 3 00 mc_currency GBP settle
66. nts Standard FORMS or via the PayPal Web Services APIs for Express Checkout MassPay or RefundTransaction If the payment has a Pending status you receive another IPN when the payment completes 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 Included in the notification is the customer s payment information such as customer name payment amount All possible variables in IPN posts are detailed in this guide When your server receives a notification it must process the incoming data 3 Your server must then validate the notification to ensure that it is legitimate Setting Up IPN Setting up IPN has two parts 1 Activating IPN for your PayPal account 2 Setting up a program on your website to process the IPN FORM variables Activating IPN To activate IPN you can either change a setting in your PayPal Profile or include the notify url variable in the payment FORMS on your website Profile Setting 1 Log in to your Business or Premier PayPal account 30 October 2006 Order Management Integration Guide Instant Payment Notification IPN IPN Notification Validation Preventing Fraud 2 Click the Profile subtab 3 Under Selling Preferences click Instant Payment Notification Preferences 4 Click Edit 5 Click the checkbox and enter the URL of
67. o a PayPal Payment Details page which displays the details of the payment he is about to make Parents by PayPal Payment Details Therisattion PayPal is the secure payment processor for your seller To continue PRIVACY please enter the required information below j BBBOnLine Pay To Widget Warehouse Payment For Widget Currency U S Dollars E Amount 142 50 USD PayPal Login Email Address faceboe paypal com Problems logging in PayPal Password Forget your password Step 3 Bob enters his PayPal account information into the PayPal Login fields 20 October 2006 Order Management Integration Guide Payment Data Transfer How PDT Works 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 Payments by ico Lac Confirm Your Payment Check the following details and click the Pay button below to complete your payment Pay To Globe Industries Inc User Status Unverified Business Member 0 Payment For Widget Quantity 1 Currency U S Dollars Amount 142 50 USD Shipping amp Handling 20 00 USD Total Amount 162 50 USD Source of Funds U S Dollar Balance 162 50 USD More Funding Options Shipping Information Ship to 1234 Main Street Walnut Creek CA 95599 x Add Address C No shipping address required
68. oad My History Download My History Download My History gives you many options for selecting the transactions and fields to save to your local computer To access the Download My History page 1 In the upper right corner of the History page click Download My History FIGURE 4 2 Download My History My Account Send Money Request Money Merchant Services Auction Tools Products amp Services Overview AddFunds Withdraw History Resolution Center Profile Download History Secure Transaction El Choose from one of the two options below Cast mize Download Custom Date Range Fields Download all payments that started within the date range you Downloadable specify History Log Updates Prom fiz TRE ie Ei otice Month Day Year Month Day Year View changes to 2005 aif File Types for Download file format C Last Download to Present New Learn More Use this new option to download all completed payments since 9 16 2005 Note The first time you use this option the start date will default to a week prior ta the current date File Types for Download Select Include Shopping Cart details comma and tab delimited files only Learn More Download History Choosing a Date Range To download your history specify the dates in the same manner as you do for basic search as detailed in Basic Search Time Periods on page 40 Selecting a File Format and Transaction Categories Y
69. or recording transactions in your PayPal account Name of counterparty If counterparty is a PayPal verified user this field will contain the user s first and last name If counterparty is not a verified user field will contain the user s email address Format M M D D Y YYY HH MM SS Alphanumeric three character codes alphanumeric 128 character limit Payment Button Variable first namel ast name Related IPN Variable payment dat e subscr date Order Management Integration Guide October 2006 71 mE Downloadable History Log Columns and Values TABLE B 1 Downloadable History Log Columns and Values 72 Column Heading Description Format Type Type of transaction Add Funds from a Bank Account ATM Withdrawal limit ATM Withdrawal Reversal Auction Payment Received alphanumeric 39 character Auction Payment Sent Canceled Fee Canceled Payment Canceled Transfer Chargeback Settlement Check Withdrawal from PayPal Currency Conversion Debit Card Cash Advance Debit Card Purchase Dividend From PayPal Money Market eCheck Received eCheck Sent Funds Added with a Personal Check Guarantee Reimbursement Payment Received Payment Sent PayPal PayPal Balance Adjustment Referral Bonus Refund Shopping Cart Payment Received Shopping Cart Payment Sent Subscription Payment Received Subscription Payment Sent Transfer Update to Add Funds from a Bank Account Update to D
70. ou can choose among four file formats Each file format can include all activity but the comma delimited and tab delimited formats are limited to either completed or balance affecting payments 1 Comma delimited 42 October 2006 Order Management Integration Guide Transaction History and Reporting Tools Download My History All activity Completed payments Balance affecting payments 2 Tab delimited All activity Completed payments Balance affecting payments 3 Intuit Quicken qif file format 4 Intuit QuickBooks iif file format Completed Transactions Since Last Download You can use the Last Download to Present feature to coincide with your consecutive accounting periods It includes only completed transactions in either comma delimited or tab delimited format Customizing the Download Selecting Transaction Fields You can also include any of the fields shown in Figure 4 3 Customize My History Download on page 44 Which of these fields you include in the downloaded file depends on what you want to do with the downloaded data The transaction history always contains the default fields listed below The meanings of these fields are described in Appendix B Downloadable History Log Columns and Values Date Time and Timezone Name Type Status and Currency Gross Fee and Net From Email Address and To Email Address Transaction ID and Reference Transaction ID Receipt ID B
71. should never give your PayPal password to anyone including PayPal employees Enabling Payment Data Transfer To enable PDT 1 Click the My Account tab 2 Click the Profile subtab Order Management Integration Guide October 2006 23 mum Payment Data Transfer Enabling Payment Data Transfer 3 Click the Website Payment Preferences link as shown in the following snapshot Selling Preferences Auctions Payment Receivin Preferences Instant Payment Notification Preferences Reputation Customer Service Message Website Payment Preferences mm Custom Payment Pages Invoice Templates Language Encoding Encrypted Payment The Website Payment Preferences page opens 4 Click the Payment Data Transfer On radio button as shown in the following diagram Payment Data Transfer optional Payment Data Transfer allows you to recei are made The use of Payment Data Trans your Return URL Please note that in order on Auto Return Payment Data ion Transfer cr 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 Your identity token also appears in this message 24 October 2006 Order Management Integrat
72. t different URLs for example if you need to separate payments to different websites you run use the notify_url variable to pass the notification URL With each payment PayPal saves the value of the notify url for a specific payment and any subsequent updates to that payment such as a cleared eCheck are sent to that notify url When you pass a notify url in your post it overrides the setting in your Profile Note The value of notify url must be URL encoded Profile Setting If you want to receive your IPNs at only a single URL enter that URL in the Preferences section of your Profile Likewise the shared secret you can use to validate that you have received an IPN can be set either with each individual payment transaction or globally in your Profile for all transactions Per Transaction If you want a distinct shared secret for each notification for each payment append a FORM variable name and a shared secret value to the value of the notify url variable When you pass a shared secret in your payment post it overrides the setting in your Profile Profile Setting If you want the same shared secret for each and every transaction enter that shared secret in the Preferences section of your Profile Shared Secret Validation The 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 October 2006 Order Managemen
73. t Integration Guide Instant Payment Notification IPN IPN Notification Validation Preventing Fraud variable to which the IPN data is posted after a payment is made The shared secret consists of the following notify_ur1 yourlPNnotificationURL shared secret variable name shared secret value where yourIPNNotificationURL is a URL on your website at which you want to receive notification shared secret variable name is any variable name you want shared secret value is the shared secret itself For example the value of notify url variable might look like this notify url https 3A www mysite com PP IPN Validate cfm secret shhhhhhh Security Considerations with Shared Secret Validation To ensure the security of your shared secret you should use Encrypted Website Payments EWP For information about EWP see the PayPal Website Payments Standard Checkout Integration Guide The value of the shared secret is not encrypted it is in clear text for easier processing Therefore the shared secret value is recorded in your web server s access log Be sure to practice proper security for your server access logs If you use a web server hosting service ensure that your provider practices proper security of your data NOTE Your notification URL should check the validity of the returned shared secret and flag for investigation any transaction that does not have the correct shared secret Your HTTPS Postback to PayPal The second met
74. tification Variables Variable txn type txn type txn id case id Case type case creation date reason code Possible Values new case adjustment complaint chargeback Transaction specific Depends on value of case type Description A new case has been registered A case has been resolved and closed The merchant s original transaction identification number for the payment from the buyer against which the case was registered Case identification number Format PP nnn nnn nnn where n is any numeric character e complaint A buyer has logged a complaint through the PayPal Resolution Center e chargeback A buyer has filed a chargeback with his credit card company which has notified PayPal of the reason for the chargeback Date and time case was registered in the following format HH MM SS DD Mmm YY YYYY PST Reason for the case reason code Values for case type complaint non receipt Buyer claims that he did not receive goods or service October 2006 Order Management Integration Guide IPN and PDT Variables SN PDT Specific Variables TABLE A 10 Dispute Notification Variables Possible Variable Values Description not as Buyer claims that the goods or service received differ from described merchant s description of the goods or service reason code Values for case type chargeback unauthorized adjustment case that has been resolved and close requires a reimburse re
75. to cross reference the payment Order Management Integration Guide October 2006 63 64 IPN and PDT Variables Mass Payment Subscriptions Variables Along with other IPN variables the following variables are included in Subscriptions IPNs TABLE A 8 Subscriptions Variables Possible Variable Values txn_type subscr failed subscr cancel subscr payment subscr signup subscr eot subscr modify subscr date subscr effective periodl period period3 amount 1 amount 2 amount 3 mc amount 1 mc amount2 Character Description Limit 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 subscr modify subscription modification Start date or cancellation date depending on whether transaction 15 subscr_signupor subscr cancel Time Date stamp generated by PayPal in the following format HH MM SS DD Mmm YY YYYY PST Date when the subscription modification will be effective only for txn type subscr modify Time Date stamp generated by PayPal in the following format HH MM SS DD Mmm YY YYYY PST optional Trial subscription interval in days weeks months years example a 4 day interval is 1 4 D optional Trial subscription interval in days weeks months or years Regular subscription interval
76. tton Related IPN Column Heading Description Format Variable Variable Option I Value Entered by buyer in any of the following website fields e PayPal Shopping Cart Option 1 Value e Buy Now Option Value e Subscription Option I Value Or specified by seller in any of the following button creation fields e PayPal Shopping Cart Value 1 Choices e Buy Now Value 1 Choices e Subscription Value 1 Choices Option 2 Name Specified by seller in any of the following button creation fields e PayPal Shopping Cart Option 2 Name e Buy Now Option 2 Name e Subscription Option 2 Name Option 2 Value Entered by buyer in any of the following website fields e PayPal Shopping Cart Option 2 Value e Buy Now Option 2 Value e Subscription Option 2 Value Or specified by seller in any of the following button creation fields e PayPal Shopping Cart Value 2 Choices e Buy Now Value 2 Choices e Subscription Value 2 Choices Name of Auction Site eBay Yahoo Auctions uBid com Amazon com Auctions MSN Auctions BidVille Other Auction Site Item URL URL of eBay Auction Item eBay Auction specific alphanumeri onl c 30 character limit alphanumeric onl 60 character limit alphanumeric 051 30 character limit alphanumeric 20 character limit alphanumeric 256 character limit option name 2 option selectionl option selection2 76 October 2006 Order Management Integration Guide Downloadable History Log Col
77. umns and Values TABLE 1 Downloadable History Log Columns and Values Payment Button Related IPN Column Heading Description Format Variable Variable Closing Date Close date of eBay Auction Item M M D D Y eBay Auction specific YYY Reference Txn ID Transaction ID of parent transaction alphanumeric 17 character limit Invoice Number Specified by seller in any of the alphanumeric invoice invoice following button creation fields e PayPal Shopping Cart Invoice Number e Buy Now Invoice Number e Subscription Invoice Number Subscription PayPal generated Subscription alphanumeric subscr id Number Transaction ID Number 19 character S XXXXXXXXXXXXXXXX limit where x is the transaction ID Custom Number Specified by seller in any of the alphanumeric custom custom following button creation fields e PayPal Shopping Cart Custom Number e Buy Now Custom Number e Subscription Custom Number Shipping Address First line of shipping address as alphanumeric address Line I specified by counterparty 395 character streetl limit Shipping Address Second line of shipping address as alphanumeric address Line 2 specified by counterparty if 395 character street2 applicable limit Town City Town City of shipping address as alphanumeric address cit specified by counterparty y State Province Regi State Province Region Territory Prefe address on County Territor cture Republic of shipping address as state y Prefecture Repub specified by counterparty
78. unique id x 63 upgrade 58 URL encoding in IPN data 51 USD 17 username 65 V verify 58 verify sign 52 virtual terminal 59 Voided 55 57 W web 59 Yen 17 October 2006 87 Z Zloty 17 88 October 2006 Order Management Integration Guide
79. you are not being spoofed You have two methods by which you can validate the notification Order Management Integration Guide October 2006 31 32 Instant Payment Notification IPN IPN Notification Validation Preventing Fraud Sending a shared secret that only you know described in Shared Secret Validation on page 32 PayPal recommends this method because it ensures the validity of the data and decreases network traffic to and from your website Shared secret validation is appropriate if you are not using a shared website hosting service if you have enabled SSL on your web server if you are using PayPal Encrypted Website Payments if you use the notify url variable on each individual payment transaction Sending a POST back to PayPal after you receive the IPN and verify the correctness of the data described in Your HTTPS Postback to PayPal on page 33 Postback is appropriate if you rely on a shared website hosting service if you do not have SSL enabled on your web server Both methods rely on the concept of a notification URL which is described in the next section Shared Secret Per Transaction or by Profile Setting The URL to which PayPal posts IPN data is called the notification URL It can be set either with each individual payment transaction or globally in your Profile for all transactions Per Transaction If you want to receive payment notifications for different payments a

Download Pdf Manuals

Related Search

Related Contents

Hotpoint FDFF Dishwasher User Manual  Samsung LE15S51B Инструкция по использованию  Samsung UA40J5100AR manual de utilizador  IMPMET Instruction manual  .. i  

Copyright © All rights reserved. Failed to retrieve file