Home

PayPal Order Management - 2008 Integration Guide

1. 47 Reporting Disputed Transactions 00000 eee eee 47 Programmatic Access to Dispute Report 0 e e 48 Appendix A IPN and PDT Variables 4 51 About These Tables of Variables 2 2 0 o 2 o 51 Transaction Specific Variable Values o a ee 51 test ipn Variable in Sandbox a e 51 IPN Variables in All Posts 2 e o 52 IPN Version notify version o oo 52 Security Information verify sign 0 o e e 52 Buyer Information a e a 52 Basic Information e e a aus grs cy mod E ata e e o de BO e RR 53 Advanced and Custom Information o e 54 Website Payments Standard Website Payments Pro and Refund Information 55 Currency and Currency Exchange 00002 eee ee ee 60 AUCIONS o Bits ce eee ata en ce oe ee qi eh ae es oe ee Ge Era SU 62 Mass Payment sels aa 4 0 24 928 be bee dee ee baw ae eee E Dam PR a 62 SUBSCMPIONS coco eam da OPA Se ica bw bee ue a bes 64 Subscriptions Variables 1 1 oaa a a a a 64 Dispute Notification Variables o ooo a a a A 68 4 March 2008 Order Management Integration Guide Contents a Miscellaneous and Fee Related IPN Variables 2 70 PDT Specific Variables o oa a ee 70 Appendix B Downloadable History Logs 71 INOX ou
2. on page 10 e For subscription IPN notifications such as signup cancel modify failed and eot mc currency is the currency of the subscription rather than the currency of the payment Example 1 If a user with a USD balance receives a 100 USD payment the following variables will be used for the payment e mc gross payment gross e mc fee payment f EXAMPLE 3 1 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 March 2008 first technical draft 29 Instant Payment Notification IPN Using IPN with Multiple Currencies Example 2 f a user with a CAD balance receives a 100 CAD payment the following variables will be used for the payment e mc grossandmc_ fee have values e payment gross and payment fee are blank EXAMPLE 3 2 Multi currency IPN CAD Payment payment status Completed payment gross payment fee mc gross 100 mc fee 3 00 mc currency CAD Example 3 If the account is set to automatically convert payments these variables will be used to show the conversion This example is for a user with a USD balance who receives a payment of 100 GBP EXAMPLE 3 3 Multiple 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
3. Select the Last Download to Present radio button to download transactions that occurred after the last time you downloaded history and select a File Type for Download Your choices are Comma Delimited Completed Payments Tab Delimited Completed Payments Intuit Quicken qif file format Intuit QuickBooks 11f file format Select the Include Shopping Cart details checkbox if you want your downloadable history log to include a row of information for each item associated with shopping cart payments Click the Download History button When prompted select whether to open the downloadable history log or to save it on your local computer Selecting Which Fields to Include in the Download Downloadable history logs always contains these fields 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 Balance For details about these default fields see Appendix B Downloadable History Logs In addition you can select other fields to include using the Customize My History Download page To select the optional fields you want to include in downloadable history logs Order Management Integration Guide March 2008 43 44 Transaction History and Reporting Tools Downloading History 1 In the upper right area of the History Download page click the Customize Downloa
4. 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 64 given to subscriber to access the subscription password optional Password generated by PayPal and given 24 to subscriber to access the subscription password will be encrypted Order Management Integration Guide March 2008 65 66 IPN and PDT Variables Subscriptions TABLE A 1 Subscriptions Variables Variable Possible Values subscr id Description ID generated by PayPal for the subscriber Char Limit 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 2 IPN Variables with Each Subscription Event Variable Signup Cancel Basic Information Payment Modify USD Payment Multi Currency Refund Failed EOT 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 item number X X X
5. business paypal com to access the PayPal Reporting User s Guide and to use the additional reporting tools To access the history and tools described here 1 Log in to your Business or Premier account 2 Click the History subtab The History page appears as shown in Figure 4 1 The History Page Order Management Integration Guide March 2008 35 36 Transaction History and Reporting Tools Using Monthly Account Statements FIGURE 4 1 The History Page Click these links to access Click the View button to activate different history functions monthly account statements History Basic Search View up to three months of Advanced Search monthly account statements Download My History Search Report 4 be Show All Activity Simple View Business Overview TORT view reports on sales O Within The Past Day Y disputes and other SS financial activity O From f 111 14 2007 Month Day Year w 2 7 007 for Month Day Year Recent Activity Last updated 12 14 2007 14 26 PST All Activity Simple View from Nov 14 2007 to Dec 14 2007 Date Type To From Name Email Status Details Nov 30 2007 Payment From Super Beamdaddy Completed Details MM A Mobile Mass Pay Money Market Debit Card Referrals AboutUs Accounts Fees Pris Security Center Contact Us Legal Agreements Developers Shops Using Monthly Account Statements
6. txn id x mc currency x mc fee x Possible Values Transaction specific for multiple currencies Transaction specific for multiple Currencies Char Description Length For Mass Payments a unique transaction ID generated by the 19 PayPal system where x is the record number of the mass pay item For Mass Payments the currency of the amount and fee where x is the record number the mass pay item For Mass Payments the transaction fee associated with the payment where x is the record number the mass pay item March 2008 Order Management Integration Guide IPN and PDT Variables Mass Payment TABLE A 7 IPN and PDT Variables Mass Payment Variable Name mc gross X payment _ date payment fee x payment _ gross xX payment _ status reason_code receiver _ email x status x Possible Values Transaction specific for Multiple Currencies Transaction specific for USD payments only Transaction specific for USD payments only Completed Denied Processed 1001 1003 1004 Completed Failed Reversed Unclaimed Char Description Length The gross amount for the amount where x is the record number the mass pay item For Mass Payments the first IPN is the date time when the 28 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 If the payment is USD then the value is the same as
7. 30 2007 H i Month Day Year H L 1 IMPORTANT The duration of the date range you specify affects how quickly you can view the search results The longer the duration the longer the search results take For faster results narrow the date range Downloading History The Download History page lets you specify a time frame for payments and transactions to include in downloadable history logs which are files that you save on your local computer You can also specify which fields to include and what file format your want To to create a downloadable history log and save it on your computer 1 In the upper left area of the History page click the Download My History link History History Basic Search View up to three months o Advanced Search monthly account state Click here to access the Download My History Download History page Search Reports The Download History page appears Order Management Integration Guide March 2008 41 42 Transaction History and Reporting Tools Downloading History FIGURE 4 2 Download History Page Download History Choose from one of the two options below Customize Download Fields Click here to select which fields to include Custom Date Range Download all payments that started within the date range you Downloadable specify History Log Updates From 12 Jya 7f007 2 fit 7 2007 Quicken F E 5 Notice Month Day Year Month Day Year View c
8. and the currency carried inmc_currency are correct for the item carried in item name or item number After you complete the above checks notification validation is complete You can update your database with the information provided and you can initiate other appropriate automated back end processing Handling Invalid Responses to Your Postback When you receive an INVALID postback response you should investigate In some cases these responses result from an IPN error possibly from a change in the IPN format To determine if an INVALID response results from an IPN error first examine your code Your postback must include exactly the same variables and values that you receive in the IPN posted to your server by PayPal and they must be in the same order 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 11 As a result your IPN notifications will then include information about the currency of the payment The following overview explains how IPN interacts with multiple currencies Norte 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 U S Dollars you will need to set up your buttons for your currency of choice March 2008 first technical draft Order Management Integratio
9. com us DISPUTE REPORT SCHED LOGIN METHOD post gt lt INPUT TYPE hidden NAME day VALUE 16 gt lt INPUT TYPE hidden NAME month VALUE 09 gt lt INPUT TYPE hidden NAME year VALUE 2006 lt INPUT TYPE hidden NAME uname VALUE yourAliasUsername gt lt INPUT TYPE hidden NAME pword VALUE yourAliasPassword gt lt INPUT TYPE image VALUE Submit gt lt FORM gt Additional Set Up You will receive an email informing you that the report is ready Be sure to monitor your primary email address for an email stating the download report is ready This email contains a hyperlink to the report which can you access with a browser You can also use the email as a trigger for your script that programmatically retrieves the report Order Management Integration Guide March 2008 first technical draft 33 a Instant Payment Notification IPN Dispute Notification and Downloadable Dispute Report 34 March 2008 first technical draft Order Management Integration Guide Transaction History and Reporting Tools With transaction history and reporting tools you can access monthly account statements search your account history for different kinds payments and transactions download history to your local computer and access reports about disputed transactions NoTE PayPal offers an additional set of reporting tools from the PayPal Business Overview page Visit the page at https
10. settle currency USD 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 Multiple 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 USD in the following example EXAMPLE 3 5 Pending Convert to Primary Currency payment status Completed 30 March 2008 first technical draft Order Management Integration Guide Instant Payment Notification IPN E Dispute Notification and Downloadable Dispute Report payment gross payment fee mc gross 100 mc fee 3 00 mc currency GBP settle amount 145 5 settle currency USD 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 mc currency GBP Ifthe payment is denied EXAMPLE 3 7 Pending Denied payment status Denied payment gross mc gross 100 mc currency GBP Norte If a user receives a payment into a currency balance and later converts this amount into another currency balance the correspondi
11. Address First line of shipping address as alphanumeric address _ Line 1 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 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 March 2008 77 E Downloadable History Logs 78 TABLE B 1 Fields and Values in Downloadable History Logs Field Name Balance Description Account balance at time of 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 signed decimal Payment Button Related IPN Variable Variable March 2008 Order Management Integration Guide Index A cc 70 chargeback 69 address 58 CHF 11 address city 52 cm 70 address country 52 i complaint 69 address country code 52 Completed 55 57 address name 52
12. Customer s company name if customer represents a business 127 business name payer email Customer s primary email address Use this email to provide any 127 credits payer id Unique customer ID 13 payer verified Customer has a Verified PayPal account status unverified Customer has an Unverified PayPal account contact Customer s telephone number 20 phone residence Two character ISO 3166 country code 2 country Basic Information TABLE A 2 IPN and PDT Variables Basic Information Variable Possible Char Name Values Description Length business Email address or account ID of the payment recipient that is the 127 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 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 Order Management Integration Guide March 2008 53 IPN and PDT Variables Advanced and Custom Information TABLE A 2 IPN and PDT Variables Basic Information 54 Variabl
13. RA a 23 Setting Up IPN ooo o ee A A A a A ES 24 Activating IPN for Your PayPal Account o o 24 Setting Up an IPN Processing Program o o e 25 Using IPN Notification Validation to Help Prevent Fraud 2 26 Using Shared Secrets for Validation a 2 26 Using Postbacks for Validation 0 o a 27 Order Management Integration Guide March 2008 E Contents Using IPN with Multiple Currencies o e 28 payment_gross and payment fee A 29 Examples of Multi currency IPN Variables o 29 Dispute Notification and Downloadable Dispute Report 31 Downloadable Dispute Report 000002 eee eee 32 Chapter 4 Transaction History and Reporting Tools 35 Using Monthly Account Statements 000002 eee eee 36 Searching History 2 0000 ee A 37 Basic Searching by Activity 00000022 ee ee 38 Advanced Searching by Field Value 20000002 ee eee 39 Specifying Date Ranges for Basic and Advanced History Search 40 Downloading History e acs ea e e A 41 Selecting Which Fields to Include in the Download 2 43 Understanding the Status and Life Cycle of Transactions 46 Reconciling Transactions using the Balance Impact Column 46 Reconciling Transactions Using the Net Amount Column
14. S Dollar Balance 162 50 USD More Funding Options Shipping Information Ship to 1234 Main Street Walnut Creek CA 95599 Add Address No shipping address required 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 Order Management Integration Guide March 2008 15 Payment Data Transfer PDT How PDT Works Payments by PayPal Global Industries Inc GD Anausties Widget Warehouse 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 18 For more information about the HTTP POST see PDT Notification Synch on page 19 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 sent to him by email The page also displays
15. 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 onl 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 March 2008 Order Management Integration Guide IPN and PDT Variables al Subscriptions TABLE A 2 IPN Variables with Each Subscription Event Payment Payment Multi Variable Signup Cancel Modify USD Currency Refund Failed EOT payment date X X txn id X X parent txn id X X txn_type subscr subscr subscr_ subscr payment subscr 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 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 Order Management Integration Guide March 2008 67 68 IPN and PDT Variables Dispute Notification Variables TABLE A 2 IPN Variables with Each Subscription Event Variable Subscription Information subscr date subscr effective periodl period2 period3
16. You can use shared secrets for IPN notification validation by including them in the programming code that your website sends to PayPal when people pay you As an alternative can set a shared secret in your account profile When your IPN processing program receives an IPN it must compare that the shared secret in the post from PayPal matches the shared secret that you expect for notifications about that payment If the secret posted by PayPal does not match the secret that you expect flag the IPN for further investigation March 2008 first technical draft Order Management Integration Guide Instant Payment Notification IPN ER Using IPN Notification Validation to Help Prevent Fraud Including Shared Secrets in Programming Code If you use shared secrets for IPN notification validation PayPal recommends that you include shared secrets in all the programming code that your website sends to PayPal when people pay you Add a shared secret variable and value to the value of the notification URL that you include in your programming code Use the following format to specify a shared secret as part of a notification URL in your programming code yourlPNnotificationURL shared secret variable name shared secret value where yourlPNNotificationURL is the URL where you receive IPNs shared secret variable name is any variable name that you want shared secret value is the shared secret itself For example the value of the notification URL varia
17. a PayPal Payment Details page which displays the details of the payment he is about to make Order Management Integration Guide March 2008 13 14 Payment Data Transfer PDT How PDT Works Payments by PayPal Global Industries Inc Widget Warehouse Payment Details Secure Transaction E 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 odeboe paypal com Problems logging in PayPal Password Forget your password Continue Step 3 Bob enters his PayPal account information into the PayPal Login fields Step 4 Bob is then taken to a confirmation page that displays the details of his selection information about how his automatic payments will be funded and his shipping information He clicks the Pay button to complete the payment March 2008 Order Management Integration Guide Payment Data Transfer PDT How PDT Works Payments y PayPal EM Indust A 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 Ed Amount 142 50 USD Shipping amp Handling 20 00 USD Total Amount 162 50 USD Source of Funds U
18. amount 1 amount 2 amount 3 mc _amountl mc amount 2 recurring reattempt retry at recur times username password subscr_id Signup Cancel X A xo x Mo x Payment Multi Currency Payment Modify USD Refund Failed EOT gt a gt A wm KK KR XXX x OK x eK KK XXX OK OK x xe KM XK x XxX Mm XK p gt gt gt Dispute Notification Variables TABLE A 8 Dispute Notification Variables Variable txn type Possible Values Description new_case new_case A new case has been registered adjustment adjustment A case has been resolved and closed March 2008 Order Management Integration Guide IPN and PDT Variables Dispute Notification Variables TABLE A 8 Dispute Notification Variables Possible Variable Values Description txn id The merchant s original transaction identification number for the payment from the buyer against which the case was registered case id Case identification number Format PP nnn nnn nnn where n is any numeric character case type complaint e complaint A buyer has logged a complaint through the chargeback 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 case __ Transaction Date and time case was registered in the following format creation specific HH MM SS DD Mmm YY YYYY PST date reason code Depends on Reason for the case value of Va
19. cart transaction see Table A 4 IPN and PDT Variables Website Payments Standard Website Payments Pro and Refund Information on page 55 for more information option Option 1 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 Website Payments Pro and Refund Information on page 55 for more information March 2008 Order Management Integration Guide IPN and PDT Variables Website Payments Standard Website Payments Pro and Refund Information TABLE A 3 IPN and PDT Variables Advanced and Custom Information Variable Possible Char 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 Website Payments Pro and Refund Information on page 55 for more information 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 Website Payments Pro and Refund Information on page 55 for more information Website Payments Standard Website Payments Pro and Refund Information TABLE A 4 IPN and PDT Variables Website Payments Standard Website Payments Pro and Refund Information Variable Possible Char Name Values Description Length auth id Transaction
20. 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 58 March 2008 Order Management Integration Guide Website Payments Standard Website Payments Pro and Refund Information IPN and PDT Variables TABLE A 4 IPN and PDT Variables Website Payments Standard Website Payments Pro and Refund Information Variable Possible Char 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 A 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 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 s
21. 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 mc handling Total handling amount associated with the transaction If this is a shopping cart transaction see Table A 4 IPN and PDT Variables Website Payments Standard Website Payments Pro and Refund Information on page 55 for more information mc_shipping 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 Website Payments Pro and Refund Information on page 55 for more information payment fee Transaction USD transaction fee associated with the payment specific for payment gross minus payment fee equals the amount USD payments deposited into the receiver email account Is empty for non USD only 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 Usemc fee instead 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 a USD payments legacy field replaced by mc_gross If this amount is negative it only signifies a refund or reversal and either of those payment
22. that for mc fee x where x is the record number if the currency is not USD then this is an empty string NOTE This is a deprecated field Usemc fee x instead If the payment is USD then the value for this is the same as that for the mc_gross_x where x is the record number the mass pay item If the currency is not USD this is an empty string NOTE This is a deprecated field Usemc gross x instead Completed For Mass Payments this means that all of your payments have been claimed or after a period of 30 days unclaimed payments have been returned to you Denied For Mass Payments this means 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 This variable is only set if status Failed 1001 Invalid UserID 1003 Country of Residence check failure 1004 Country of Funding Source check failure For Mass Payments the primary email address of the payment 127 recipient where x is the record number of the mass pay item For Mass Payments the status of the payment where x is the record number Completed The payment has been processed regardless of 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
23. the funds have been returned because the Receiver s account was locked Unclaimed This is for unilateral payments that are unclaimed Order Management Integration Guide March 2008 63 IPN and PDT Variables Subscriptions TABLE A 7 IPN and PDT Variables Mass Payment Variable Possible Char Name Values Description Length 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 to cross reference the payment Subscriptions Subscriptions Variables Along with other IPN variables the following variables are included in Subscriptions IPNs TABLE A 1 Subscriptions Variables Possible Variable Values ubscr ailed txn_type s f subscr Cancel subscr payment subscr signup subscr eot s ubscr modi fy subscr date subscr effective Description Char Limit ubscr signup subscription sign up ubscr cancel subscription cancellation ubscr failed subscription payment failure ubscr payment subscription payment ubscr eot subscription s end of term S S S S S S ubscr modify subscription modification Start date or cancellation date depending on whether transaction is 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 effecti
24. 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 e test ipn Variable in Sandbox on page 51 e IPN Variables in All Posts on page 52 e Buyer Information on page 52 e Basic Information on page 53 e Advanced and Custom Information on page 54 e Website Payments Standard Website Payments Pro and Refund Information on page 55 e Currency and Currency Exchange on page 60 e Auctions on page 62 e Mass Payment on page 62 e Subscriptions on page 64 e Dispute Notification Variables on page 68 e PDT Specific Variables on page 70 Transaction Specific 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 March 2008 51 IPN and PDT Variables IPN Variables in All Posts IPN Variables in All Posts IPN Version notify_ve
25. 1 new case 68 NOK 11 non receipt 69 Norwegian Krone 11 not as described 69 notification 24 notification URL 24 25 notification validation 26 notify version 52 num cart items 56 NZD 11 O option name 1 54 option name 2 54 option namel 54 56 option name2 54 56 option selection 54 option selection x 56 option selection 55 option selection 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 63 payment fee 61 payment fee x 63 March 2008 Order Management Integration Guide payment gross 61 payment gross x 63 payment status 51 63 payment type 57 PayPal supported currencies 11 Pending 55 57 pending reason 58 periodl 65 period 65 period3 65 PLN 11 Polish Zloty 11 Pound Sterling 11 Processed 57 Q qif file format 42 43 quantity 54 QuickBooks 43 Quicken 42 43 R reason code 59 63 69 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 11 send money 60 settle amount 61 settle currency 61 SGD 11 shipping 59 sig 70 Order Management Integration Guide Index Singapore Dollar 11 special 69 st 70 status x 63 subscr cancel 64 subscr date 64 subscr effective 64 subscr eot 64 subscr failed 64 subscr id 66 subscr modify 64 sub
26. After you activate monthly account statements you can view them from the History page New statements become available on the 15th of each month and they remain available online for up to three months To activate monthly account statements 1 From the My Account Overview page click the History subtab The History page appears 2 Click the View button March 2008 Order Management Integration Guide Transaction History and Reporting Tools ES Searching History 3 On the displayed page click the Yes radio button 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 Would you like to receive Monthly Account Statements ves No Cancel 4 Click the Save button Searching History There are two ways to search your account history for payments and other activity e Basic Searching by Activity specify a kind of account activity and specify a date range e Advanced Searching by Field Value specify a value or a pattern of values in a specific field and specify a date range Order Management Integration Guide March 2008 37 4 Transaction History and Reporting Tools Searching History Basic Searching by Activity From the History page you can search your transaction history by specifying the kind of account activity you want to view Click here for Basic Search where you can search transactio
27. 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 ofmc 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 ofmc handling x might not be equal to mc handling Order Management Integration Guide March 2008 55 IPN and PDT Variables Website Payments Standard Website Payments Pro and Refund Information TABLE A 4 IPN and PDT Variables Website Payments Standard Website Payments Pro and 56 Refund Information Variable Possible Char Name Values Description Length mc Transaction This is the combined total of shipping and shipping2 shipping x specific for Website Payments Standard variables where x is the shopping multiple cart detail item number The shippingx variable is only shown currencies when the merchant applies a shipping amount for a specific item Because profile shipping might apply the sum of shippingx migh
28. C off Identity Token ime8wn6 ZISilI9BdnDY4g570zrgYomzimewy Xqrwb44 5qFjLhBeiR 3cUFhe 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 and PayPal Account Optional The PayPal Account Optional does not require your customers who are new to PayPal to create a PayPal account to complete a purchase they go through an alternate checkout and have the option to sign up afterward Customers who already have PayPal accounts will continue to enjoy the privileges of those accounts such as payment history and integration with eBay Auctions and their checkout experience will remain the same This PayPal Account Optional feature is available for Buy Now Donations and Shopping Cart buttons but not for Subscription buttons PayPal Account Optional is enabled by default If the merchant has turned on Payment Data Transfer and has not disabled PayPal Account Optional a new user will not be automatically directed back to the merchant website but will be given the option to return When the buyer clicks the Continue button the transaction ID associated with the transaction is sent The merchant returns the transaction ID along with their identity token and PayPal then sends the merchant payment information that confirms that the payment is complete The buyer is directed back to the merchant
29. 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 March 2008 PayPal Order Management Integration Guide Document Number 100009 en_US 200803 O 2008 PayPal Inc All rights reserved PayPal is a registered trademark of PayPal Inc The PayPal logo is a trademark of PayPal Inc Other trademarks and brands are the property of their respective owners The information in this document belongs to PayPal Inc It may not be used reproduced or disclosed without the written approval of PayPal Inc Copyright PayPal All rights reserved PayPal S r l et Cie S C A Soci t en Commandite par Actions Registered office 22 24 Boulevard Royal L 2449 Luxembourg R C S Luxembourg B 118 349 Consumer advisory The PayPal payment service is regarded as a stored value facility under Singapore law As such it does not require the approval of the Monetary Authority of Singapore You are advised to read the terms and conditions carefully Notice of non liability PayPal Inc is providing the information in this document to you AS IS 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 omissio
30. acter 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 March 2008 Order Management Integration Guide Downloadable History Logs Boo TABLE B 1 Fields and Values in Downloadable History Logs Payment Button Related IPN Field Name Description Format Variable Variable Item Title Specified by buyer in the website alphanumeric item name item name field 128 character y E 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 o 7 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 u
31. address state 52 address status 52 contact phone 53 currency codes 11 custom 54 address street 52 Czech Koruna 11 address zip 52 CZK 11 adjustment 68 All Activity Advanced View 39 amount 65 D amount2 65 Danish Krone 11 amount3 65 i pA Denied 57 am DKK 11 auction buyer id 62 70 auction closing date 62 auction_multi_item 62 downloadable history logs 7 41 duplicate 69 AUD 11 Australian Dollar 11 E th t 55 ee echeck 57 58 auth_exp 55 q EUR 11 auth_id 55 E ii auth status 55 y aco authorization 58 PRE Anp Ta e Expired 57 express_checkout 60 B Balance 39 F business 53 Failed 57 first_name 52 C for auction 62 Forint 11 CAD 11 fraud prevention 26 Canadian Dollar 11 Canceled Reversal 57 cart 60 G case creation date 69 case_id 69 OEH case_type 69 Order Management Integration Guide March 2008 79 H History 35 HKD 11 Hong Kong Dollar 11 HUF 11 Hungarian Forint 11 uf file format 43 instant 57 intl 58 invoice 54 item_name 53 item_number 53 J Japanese Yen 11 JPY 11 K Koruna 11 Krona 11 Krone 11 L last_ name 53 logs 7 41 masspay txn id x 62 mc amount 65 mc amount 65 mc amount3 65 mc currency 60 65 mc currency x 62 mc fee 60 61 63 mc fee x 62 63 mc gross 61 mc gross x 55 63 mc handling 61 mc handling x 55 80 mc shipping 61 mc shipping x 56 memo 54 merchandise 69 merch pmt 70 multi currency 58 N Net Amount 47 New Zealand Dollar 1
32. ailable 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 March 2008 a Introduction Differences between Payment Data Transfer PDT and Instant Payment Notification IPN e Merchant Sales Reports Every week receive valuable analysis of revenue by sales channel and currency 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 cmd p xcl rec reports intro outside Differences between Payment Data Transfer PDT and Instant Payment Notification IPN 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 Is available only to merchants who integrate PayPal with their websites by us
33. al Supported Transactional Currencies 12 March 2008 Order Management Integration Guide Payment Data Transfer PDT Merchants who use Website Payments Standard can use Payment Data Transfer PDT to display transaction details to buyers who are redirected back to the merchants websites after they complete their payments Norte You must enable Auto Return for Website Payments Standard to use Payment Data Transfer Auto Return applies to PayPal Website Payments Standard including Buy Now Donation Subscriptions Shopping Cart and Gift Certficate buttons 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 the Buy Now button dustries Inc y ff Global tr In A Wooden Widgets Rubber Widgets Aluminum Widgets The surprisingly compact Widget E 4019983763 is a powerful Steel Widgets no compromise solution for Widget 019983763 Outdoor Widgets widget professionals who are 5 frequently on the road and rarely in the office but who never want to be without the speed and power of Plastic Widgets an automotive widget It slices dices Automotive Widgets and it will even make bread Titanium Widgets Sale Price 142 50 Global Industries Inc All rights reserved 2003 Step 2 Bob is taken to
34. amt Amount of the transaction cc Currency code cm Custom message sig st Transaction status tx Transaction ID PDT token 70 March 2008 Order Management Integration Guide Downloadable History Logs TABLE B 1 Fields and Values in Downloadable History Logs Field Name Date Time Timezone Name Description 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 for 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 March 2008 71 E Downloadable History Logs TABLE B 1 Fields and Values in Downloadable History Logs 72 Field Name Type Description Format Type of transaction Add Funds from a Bank Account A ATM Withdrawal limit ATM Withdrawal Reversal Auction Payment Received alphanumeric 39 character Auct
35. and as completed in the Status column 46 March 2008 Order Management Integration Guide Transaction History and Reporting Tools ES Reporting Disputed Transactions 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 effect on your balance because they never becomes completed transactions Reconciling Transactions Using the 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 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 00EUR 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 Reporting Disputed Transactions With dispute reports you can focus only on transactions that are disputed by customers for some reason Order Management Integration Guide March 2008 47 4 Transaction History and Reporting Tools Reporti
36. ation to Help Prevent Fraud After your server receives an Instant Payment Notification you must confirm that the notification is authentic This is known as notification validation Performing notification validation for all the IPNs that you receive helps you and PayPal prevent the kind of fraud that results from 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 this data you can avoid being spoofed PayPal offers two methods for notification validation e Use shared secrets PayPal recommends this method because it ensures the validity of the data and decreases network traffic to and from your website Use shared secrets for validation if You are not using a shared website hosting service You have enabled SSL on your web server You are using Encrypted Website Payments You use the notify url variable on each individual payment transaction For more information see Using Shared Secrets for Validation on page 26 e Send a postback to PayPal Use postbacks for validation if You rely on a shared website hosting service You do not have SSL enabled on your web server For more information see Using Postbacks for Validation on page 27 Using Shared Secrets for Validation
37. ble might look like this https 3A www mysite com PP IPN Validate cfm secret shhhhhhh Note When you include a shared secret in programming code the secret is included in IPNs that are related to payments that result from the code overriding the shared secret that you may have set in your account profile Setting a Shared Secret in Your Account Profile If you want to use the same shared secret for notification verification of all IPNs you can set the secret in your account profile PayPal includes the secret you set in all IPNs except for payments that result from programming code in which you include shared secrets with the notification URL variable Security Considerations with Shared Secrets for Validation To ensure the security of the shared secrets in HTML button code that you send to PayPal use Encrypted Website Payments EWP For more information about EWP see the Website Payments Standard Integration Guide Shared secrets posted to you by PayPal through IPN are not encrypted they are in clear text for easier processing Therefore the shared secrets are recorded in the clear in the access logs of your web server Be sure to practice proper security for these logs If you use a web server hosting service ensure that your provider practices proper security of your data Using Postbacks for Validation If you cannot use shared secrets for notification validation you can use postbacks to PayPal instead Your postback must
38. d Fields link as shown below story Loss of the two options below Range ayments that started within the date range you N Eh 2007 1 h2 7 m 7 2007 Day Year Month Day Year mm a ae a a a a ae Customize Click here to select Download which fields to include Fields Downloadable History Log Updates Quicken Notice View changes to 2005 gif file format 2 In the Customize My History Download page select the checkboxes next to the fields that you want to include March 2008 Order Management Integration Guide Transaction History and Reporting Tools Downloading History FIGURE 4 3 The Customize My History Download Page Customize My History Download Check the boxes next to the fields you want to download All checked fields will be included in your downloadable log 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 Item ID Item Title Invoice Number Custom Number Shipping Amount Insurance Amount Single Column Shipping Address Address will be displayed in a single column Multi Column Shipping Address Address will be displayed in separate columns Counter Party Status Verified vs Unverified Address Status Confirmed vs Unconfirmed Sales Tax Option Names and Values Nada O AAA AE Contact Phone Number
39. d corrections to some variables in Appendix A Minor correction to values of payment_status IPN variable Description of the programmatically retrievable Dispute 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 Order Management Integration Guide March 2008 ERA Revision History 8 March 2008 Order Management Integration Guide Introduction PayPal offers four payment notification methods for back end integration e Email e Reporting e Instant Payment Notification IPN e Payment Data 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 the Save button 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 Av
40. d PDT Variables Website Payments Standard Website Payments Pro and Refund Information Variable Possible Char Name Values Description Length pending address This variable is set only if payment status Pending reason authorizati address The payment is pending because your customer did on not include a confirmed shipping address and your Payment echeck Receiving Preferences is set yo allow you to manually accept or intl deny each of these payments To change your preference go to the Preferences section of your Profile multi currency authorization You set lt PaymentAction gt Authorization lt PaymentAction gt on unilateral SetExpressCheckoutRequest and have not yet captured upgrade funds verify echeck The payment is pending because it was made by an other eCheck that has not yet cleared int1 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 Payment 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
41. e Possible Char Name Values Description Length 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 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 A 3 IPN and PDT Variables Advanced and Custom Information Variable Possible Char Name Values Description Length custom Custom value as passed by you the merchant 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 omitted no variable is passed back memo Memo as entered by your customer in PayPal Website Payments 255 note field option_ Option 1 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 Website Payments Pro 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
42. e cra a ss a a sr a O Order Management Integration Guide March 2008 5 E Contents 6 March 2008 Order Management Integration Guide Preface This Document This document describes the PayPal features for managing orders such as Payment Data Transfer PDT Instant Payment Notification IPN and Downloadable History Log This document is written for merchants who use PayPal to manage order information Revision History TABLE P 1 Revision History Date March 2008 January 2008 September 2007 August 2007 July 2007 April 2007 October 2006 July 2006 May 2006 Description Corrected the procedure for checking the postback response from PayPal when performing notification validation of IPNs See Using Postbacks for Validation on page 27 Added information on how to search for contribution payments in transaction history and what values the Type column in downloadable history logs carries for donation activity See Chapter 4 Transaction History and Reporting Tools Replaced the old PayPal logo in screen shots with the new PayPal logo Added shipping_method to Appendix A IPN and PDT Variables See the table of variables for Website Payments Standard Website Payments Pro and Refund Information on page 55 Minor bug fixing Added contact phone to IPN variables Added pointer to PayPal Business Overview page Details about the Downloadable Dispute Report Minor additions an
43. end money Transaction created by customer from the Send web accept Money tab on the PayPal website virtual terminal Transaction created with Virtual Terminal web accept Transaction created by customer via Buy Now Donation or Auction Smart Logos NOTE In some cases txn_type is blank when the variable reason code is chargeback Currency and Currency Exchange TABLE A 5 IPN and PDT Variables Currency and Currency Exchange Information Variable Possible Char Name Values Description Length exchange _ Exchange rate used if a currency conversion occurred rate mc currency Three For payment IPN notifications this is the currency of the character payment For non payment subscription IPN notifications 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 March 2008 Order Management Integration Guide IPN and PDT Variables Currency and Currency Exchange TABLE A 5 IPN and PDT Variables Currency and Currency Exchange Information Variable Possible Char Name Values Description Length mc gross Full amount of the customer s payment before transaction fee is subtracted Equivalent to payment gross for USD
44. erate a first day DDR report Subsequent Daily Reports Reports generated every day following the First DDR report contain information about dispute activity for your account in the past 24 hours or since the last report was generated including the following e New cases e Changed cases including cases that are closed Setup To use the report you must March 2008 first technical draft Order Management Integration Guide Instant Payment Notification IPN Dispute Notification and Downloadable Dispute Report 1 Create a unique user with PayPal s Multi User Access feature for downloading reports Login to your PayPal account Click the Profile subtab Under the Account Information column click Multi User Access Click Add On the Multi User Access page enter the requested information into the fields provided Click the checkboxes next to each permission you want the alias to have Click Save 2 Contact your PayPal Account Manager to sign you up for the report 3 Write a script to download the report from PayPal Scripts You can automate which details you want to be prioritized in your dispute reports by assigning values shown in the sample HTML below You can set the values for day month and year The uname value is the alias you created with the Multi User Access feature lt FORM ACTION https www paypal
45. es 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 sure you are on the real PayPal site PayPal will never ask you to enter your password in an email For more information on protecting yourself from fraud please review our Security Tips at https www paypal com securitytips Protect Your Password You should never give your PayPal password to anyone including PayPal employees Enabling Payment Data Transfer You can enable PDT from your account profile and you can enable PDT when you use a button creation tool on the PayPal website to create payment buttons for Website Payments Standard For more information about enabling PDT from a button creation tool see the Website Payments Standard Integration Guide To enable PD from your account profile Order Management Integration Guide March 2008 17 Payment Data Transfer PDT Enabling Payment Data Transfer 1 Click the My Account tab 2 Click the Profile subtab 3 Click the Website Payment Preferences link as shown in the following snapshot Selling Preferences Auctions Sales Tax Shipping Calculations Shipping Preferences UPS Preferences Payment Receiving Preferences Instant Payment Notification Preferences PayPal Shops Reputation Guarantee Preferences Seller Eligibility for PayPal Buye
46. ettle specific Capture shipping Merchant The name ofa shipping method from the Shipping Calculations method specific section of the merchant s account profile The buyer selected the named shipping method for this transaction 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 namel 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 oftax x might not total to tax transaction auth Authorization and Capture transaction entity _entity reauth order payment txn id A unique transaction ID generated by PayPal 19 Order Management Integration Guide March 2008 59 IPN and PDT Variables Currency and Currency Exchange TABLE A 4 IPN and PDT Variables Website Payments Standard Website Payments Pro and mc fee currency code See table of supported currencies Refund Information Variable Possible Char Name Values Description Length 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 items send money xpress checkout Transaction created by Express Checkout virtual when the customer s cart contains a single item terminal s
47. ge 68 Downloadable Dispute Report The Downloadable Dispute Report provides details about newly created disputes and changes in the status of cases already in mid process The report is designed for the merchant that processes payment volumes better handled by programmatic interfaces Thus while the report resembles the Dispute Report available via the Resolution Center on the PayPal site the downloadable is different in that it contains all open records records cannot be filtered and the invoice ID which can use to track dispute cases based on your transaction identifiers The report is generated every day based on activity for the previous day Days in which no activity occurred create an empty report Reports are available for seven days after which the report is no longer available The report contains information about all chargebacks and buyer complaints for your account This report does not contain information about ACH returns of PayPal unauthorized complaints First Report When you are first signed up for the DDR the report contains 1 All open Chargebacks regardless of the date the case was created or the current status of the case 2 All open Buyer Complaints regardless of the date the case was created or the current status of the case Use this report as a starting point against which you will compare all future reports If you want this first report re run contact your PayPal Account Manager and ask them to gen
48. hanges to 2005 gif File Types for Download file format E Select vi O Last Download to Present Learn More Use this new option to download all completed payments since 12 4 2007 Note The first time you use this option the start date will default to a week prior to the current date File Types for Download Select v Select the file format E for your downloadable history log O include Shopping Cart details comma and tab delimited files only Learn More Click here to create the downloadable history file after you specify all options Download History 2 In the upper right area of the History Download page click the Customize Download Fields link to select which fields you want to include in your downloadable history log For more information see Selecting Which Fields to Include in the Download on page 43 3 Specify a Custom Date Range for the history you want to download and select a File Type for Download Your choices are Comma Delimited All Activity Comma Delimited Completed Payments Comma Delimited Balance Affecting Payments Tab Delimited All Activity Tab Delimited Completed Payments Tab Delimited Balance Affecting Payments Intuit Quicken qif file format March 2008 Order Management Integration Guide Transaction History and Reporting Tools Downloading History Intuit QuickBooks 11f file format or
49. ields Field Matching Criteria Last Name Any part of the text you enter can match For example the text mit matches Smith and Mitty Last Name First Name Any part of text can match Receipt ID Exact match Invoice ID Exact match Billing Agreement Exact match Profile ID Exact match For detailed information on how to specify a date range see Specifying Date Ranges for Basic and Advanced History Search on page 40 Specifying Date Ranges for Basic and Advanced History Search You can confine your basic or advanced to search to a specific date range in these ways e Select the Within radio button and select one of these time frames from the dropdown menu The Past Day The Past Week The Past Month The Past Year RR E Select a time frame to specify the date range for a H The Past Da i basic or advanced search O From The Past Week 2007 i The Past Month PR i The Past Year i i w 2 i i Month Day Year SRRA 40 March 2008 Order Management Integration Guide Transaction History and Reporting Tools ES Downloading History e Select the From radio button and specify a date range using the text boxes for the From and To day month and year e q sm 1 H AAA 1 O Within The Past Day i E 1 From bu Gi oe Specify the From and To Month Day Year month day and year to H H specify the date range for a i Search H basic or advanced search l 11 El
50. include exactly the same variables and values that you receive in the IPN posted to your server by PayPal and they must be in the same order Constructing Your Postback Use these guidelines for constructing your postback to PayPal 1 Your postback must be sent to https www paypal com cgi bin webscr Order Management Integration Guide March 2008 first technical draft 27 28 Instant Payment Notification IPN Using IPN with Multiple Currencies NoTE You can implement IPN without SSL including your postbacks for validation but PayPal recommends against doing so 2 Your postback must include the variable cmd with the value _notify validate cmd notify validate 3 Your postback must include exactly the same variables and values that you receive in the IPN from PayPal and they must be in the same order Processing the PayPal Response to Your Postback PayPal responds to your postbacks with a single word in the body of the response VERIFIED or INVALID When you receive a VERIFIED postback response perform the following checks on data in the IPN 1 Check that the payment status is Completed 2 Ifthe payment status is Completed check the txn id against the previous PayPal transaction that you processed to ensure it is not a duplicate 3 Check that the receiver email is an email address registered in your PayPal account 4 Check that the price carried in mc_gross
51. ing Website Payments Standard e Requires 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 At the 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 eCheck clearings reversals and refunds 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 10 March 2008 Order Management Integration Guide 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 March 2008 11 E Introduction PayP
52. ion 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 Donation Received Donation Sent 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 Item 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 Debit Card Credit Update to eCheck Received Update to Payment Received Update to Payment Sent continued Payment Button Related IPN Variable Variable txn type March 2008 Order Management Integration Guide Downloadable History Logs Boo TABLE B 1 Fields and Values in Downloadable History Logs Payment Button Related IPN Field Name 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 C
53. ivity Simple View is selected by default You can scroll up the list to select All Activity Advanced View which differs from All Activity Simple View by including a Balance column The Balance column shows an ellipsis for transactions that do not affect your account balance For detailed information on how to specify a date range see Specifying Date Ranges for Basic and Advanced History Search on page 40 Advanced Searching by Field Value From the Search page you can search your transaction history for a value or a pattern of values in a specific field Click here for Advanced Search where you can search transaction history by field values History Search Search For In Email v Advanced Search DR i J saudi La O Within The Past Day Y From fp he 2007 Download My History Month Day Year To fiz fie 2007 Month Day Year Seem eee eee eee eee a Advanced Search Date Type To From Name Email Status Action Gross Fe 1 A AAA 4 In the Search For text box type the value or pattern From the In dropdown menu select one of 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 Order Management Integration Guide March 2008 39 4 Transaction History and Reporting Tools Searching History TABLE 4 2 Advanced Transaction Search Key F
54. leared 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 March 2008 73 E Downloadable History Logs TABLE B 1 Fields and Values in Downloadable History Logs Field Name Gross Fee Net Note From Email Address To Email Address Transaction ID 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 char
55. lues for case type setto complaint case type e non receipt Buyer claims that he did not receive goods or service e not as described Buyer claims that the goods or service received differ from merchant s description of the goods or service Values for case type set to chargeback e unauthorized e adjustment reimburse A case that has been resolved and close requires a reimbursement e non receipt Buyer claims that he did not receive goods or service e duplicate Buyer claims that a possible duplicate payment was made to the merchant e merchandise Buyer claims that the received merchandise is unsatisfactory defective or damaged e 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 Order Management Integration Guide March 2008 69 OA IPN and PDT Variables PDT Specific Variables Miscellaneous and Fee Related IPN Variables TABLE A 9 Miscellaneous and Fee Related IPN Variables Variable Possible Char Name Values Description Length txn type merch pmt Monthly fee for use of Website Payments Pro 64 PDT Specific Variables The following variables apply only to PDT TABLE A 10 PDT Specific Variables Variable Description
56. matically confirm that the payment status is Completed since the buyer could use methods such as eChecks that do not immediately clear For a list of PDT variables see Appendix A IPN and PDT Variables Preventing Fraud In order to prevent fraud PayPal recommends that your programs verify the following txn_id is not a duplicate to prevent someone from reusing an old completed transaction receiver email is an email address registered in your PayPal account to prevent the payment from being sent to a fraudulent account Other transaction details such as the item number and price to confirm that the price has not been changed Sample Code for PDT Sample code for the following development environments is available on the PayPal website at https www paypal com us cgi bin webser cmd p xcl rec pdt code ASP VBScript ColdFusion PERL PHP Order Management Integration Guide March 2008 21 Payment Data Transfer PDT Sample Code for PDT 22 March 2008 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 e About IPN on page 23 e Setting Up IPN on page 24 e Using IPN Notification Validation to Help Prevent Fra
57. n Guide Instant Payment Notification IPN ae Using IPN with Multiple Currencies payment_gross and payment_fee These variables reflect the amount received and corresponding fee of U S 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 NOTE payment fee is not always present in IPNs such as when a payment is pending These values are absent for non USD payments so that IPN scripts will not process these amounts as USD However legacy IPN scripts will continue to work as before as long as the merchant only receives USD payments Examples of Multi currency IPN Variables IPN notifications that use the payment_gross variable will have the following multi currency variables added The variables mc_gross and mc_ fee will not be added to IPN notifications with txn type subscr signup subscr cancel subscr modify subscr failed or subscr eot e mc gross Full amount of payment received before transaction fee Note If payment is in USD the payment _ gross value equals mc_gross e mc fee Transaction fee associated with the payment Variable function like payment fee variable variable does not appear when payment pending and so on Note If payment is in USD the payment fee value equals mc fee e mc currency Currency of mc_gross mc fee payment gross and payment fee amounts Possible values are detailed in
58. n history by the kind of account activity that you want to view History History Basic Search Advanced Search Monthly Account Statements Sep 2008 v Download My History Search Reports Show Al Activity Simple View Vit Select the type of activity that you Business Overview Within View reports on sales O The Past Day E want to view from disputes and other the dropdown menu financial activity O From 11 fie 2007 Month Day Year ch i Month Day Year Recent Activity Last updated 12 18 2007 11 42 PST All Activity Simple View from Nov 18 2007 to Dec 18 2007 Date Type To From Name Email Status De m ewww www ww ww ww ww ww ww ww ww ee ee L In the Show dropdown menu select one of the following types of account activity TABLE 4 1 Basic 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 Donations Sent or Received Transactions Received Mass Payments Refunds eChecks Money Requests Currency Conversions Preapproved Payments 38 March 2008 Order Management Integration Guide Transaction History and Reporting Tools ES Searching History TABLE 4 1 Basic Search Selectable Activity Types Funds Added or Balance Transfer Gift Certificates Withdrawn The choice All Act
59. ng Disputed Transactions FIGURE 4 5 Dispute Report 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 Al Disputes y Status a Nm Within The Past Day y e e ie 2005 Bp Po 005 Month Day Year Month Day Year ge Open Disputes and Requests All Disputes Aug 30 2005 to Sep 29 2005 Filed n dde Date Amount Reason o Type Counterparty 1D Status Details Email One gt 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 disp
60. ng currency conversion transaction has no IPN Dispute Notification and Downloadable 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 Order Management Integration Guide March 2008 first technical draft 31 32 Instant Payment Notification IPN Dispute Notification and Downloadable Dispute Report 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 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 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 pa
61. ns 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 Preface Chapter Chapter Chapter Contents al papa ds ok Siege a A a le O ew SD Eee RS oe 7 This Document ec d gen a doa oe ae a e a A ae dc de a o 7 Revision HISt0ly gt e aa AAA AAA de bhs ed 7 1 Introduction 0 0 ice a ee a sms 9 Email ass a a as hh ae an is A A E AE A 9 Reporting us dais bap hae e a a a Oe ee Beg 9 Differences between Payment Data Transfer PDT and Instant Payment Notification IPN 10 SSL Not Required for IPN aaa aaa 10 PayPal Supported Transactional Currencies ooo o a a 11 2 Payment Data Transfer PDT 13 How PDT Works 2104040324 hee A we A REA a Re ae a God a 13 Enabling Payment Data Transfer aoaaa aaa A 17 Getting and Using the Identity Token 0 0 000000 18 PDT and PayPal Account Optional o a 19 PDT Notification Synch p 2 0 E a e a a a 19 Constructing the POST e eee 20 PayPal Response to POST 0 0 A 20 PDT and Auto Return Messaging to BUyer 0 e e 21 Preventing Fraud aoaaa aa ee 21 Sample Code for PDT aaa a 21 3 Instant Payment Notification IPN 23 About IPN es ses o mr a ar a a aa A a
62. nsigned 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 on0 option name following button creation fields 60 character J o e PayPal Shopping Cart Option 1 limit Name e Buy Now Option 1 Name e Subscription Option 1 Name Order Management Integration Guide March 2008 75 E Downloadable History Logs TABLE B 1 Fields and Values in Downloadable History Logs Payment Button Related IPN Field Name Description Format Variable Variable Option 1 Value Option 2 Name Option 2 Value Auction Site Item URL Entered by buyer in any of the following website fields e PayPal Shopping Cart Option 1 Value e Buy Now Option 1 Value e Subscription Option 1 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 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 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 Bu
63. nt 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 processe payment was previously pending because of possible reasons described for the PendingReason element eee 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 payment echeck echeck This payment was funded with an eCheck type instant instant This payment was funded with PayPal balance credit card or Instant Transfer Order Management Integration Guide March 2008 57 OA IPN and PDT Variables Website Payments Standard Website Payments Pro and Refund Information TABLE A 4 IPN an
64. otification it must process the incoming data 3 Your server must then validate the notification to ensure that it is legitimate Setting Up IPN Follow these procedures to set up IPN e Activating IPN for Your PayPal Account on page 24 e Setting Up an IPN Processing Program on page 25 Activating IPN for Your PayPal Account You can activate IPN for your PayPal account through your account profile Separately you can activate IPN for specific payments by including a notification URL in the programming code that your website sends to PayPal when people pay you 24 March 2008 first technical draft Order Management Integration Guide Instant Payment Notification IPN Setting Up IPN Activating IPN Through Your Account Profile When you activate IPN through your account profile the notification URL that you specify is used for all your IPNs You can override the value on specific payment transactions by including notification URLs in the programming code that your website sends to PayPal when people pay you To activate IPN through your account profile 1 Log in to your Business or Premier account 2 Click the Profile subtab 3 In the Selling Preferences column click the Instant Payment Notification Preferences link 4 Click the Edit button 5 Select the checkbox to activate IPN 6 In the Notification URL text box enter the URL of the program that will receive and process IPNs 7 Click the Save b
65. 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 For example 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 16 March 2008 Order Management Integration Guide Payment Data Transfer PDT Enabling Payment Data Transfer Widget Warehouse Thank you for your payment Your transaction has bean completed Payment Details Amount 162 50 Please print this page for your records A receipt for your purchase has also been emailed to you Widget Email pdeboe merchantty Ship to Bob Deboe 1234 Main Street Walnut Creek CA 95599 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 PayPal Dear Bob Deboe This email confirms that you Bob Deboe have paid Widget Warehouse 162 50 using PayPal Payment Details Amount 162 50 USD Transaction ID 78H54514UY26 Quantity 1 Item Product Widget Name Protect Your Account Info Make sure you never provide your password to fraudulent websit
66. r Protection Website Payments Preference Custom meca Pages 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 C Off 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 the Save button Getting and Using the Identity Token When you click the Save button 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 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 18 March 2008 Order Management Integration Guide Payment Data Transfer PDT PDT and PayPal Account Optional 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
67. ree to four business days the transaction status changes from Uncleared to Cleared Status of Disputed Transactions Transactions with a Placed status for temporary holds usually involve a customer dispute 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 Reporting Disputed Transactions on page 47 Reconciling Transactions using the Balance Impact Column The optional 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
68. rsion 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 verify sign is an encrypted string used to validate the authenticity of the transaction Buyer Information TABLE A 1 IPN and PDT Variables Buyer Information Variable Name address _ city address country address _ country code address _ name address _ state address _ status address _ street address zip first name Possible Values confirmed unconfirmed Description City of customer s address Country of customer s address Two character ISO 3166 country code Name used with address included when the customer provides a Gift Address State of customer s address Customer provided a confirmed address Customer provided an unconfirmed address Customer s street address Zip code of customer s address Customer s first name Char Length 40 64 128 40 200 20 64 52 March 2008 Order Management Integration Guide IPN and PDT Variables Basic Information TABLE A 1 IPN and PDT Variables Buyer Information Variable Possible Char Name Values Description Length last name Customer s last name 64 payer
69. scr payment 64 subscr signup 64 Swedish Krona 11 Swiss Franc 11 T tax 55 59 test ipn 51 transaction entity 59 tx 70 txn id 59 69 txn type 60 64 68 U U S Dollar 11 unauthorized 69 unilateral 58 unique id x 64 upgrade 58 URL encoding in IPN data 51 USD 11 username 65 V verify 58 verify sign 52 virtual terminal 60 Voided 55 57 W web 60 March 2008 81 Y Yen 11 Z Zloty 11 82 March 2008 Order Management Integration Guide
70. site where the transaction information is displayed However if the buyer does not click the Continue button they will not be directed back to the merchant s site and PDT will not be initiated 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 viaa 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 Order Management Integration Guide March 2008 19 20 Payment Data Transfer PDT PDT Notification Synch Constructing the POST Here are the guidelines for constructing the PDT HTTPS POST to PayPal for notification synch 1 Your POST 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 For information about the identity token see Getting and Using the Identity Token on page 18 PayPal Re
71. sponse 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 Ifthe 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 March 2008 Order Management Integration Guide Payment Data Transfer PDT Preventing Fraud PDT and Auto Return Messaging to Buyer With 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 sent to the buyer by email You can display to your customer whatever payment details you feel are appropriate however PayPal recommends including the following Item name Amount paid Payer email Shipping address If you are using PDT to determine when to fulfill an order auto
72. statuses can be for the full or partial amount of the original transaction settle_ Amount that is deposited into the account s primary balance after amount a currency conversion from 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 Order Management Integration Guide March 2008 61 62 IPN and PDT Variables Auctions Auctions TABLE A 6 IPN and PDT Variables Auctions Variable Name auction buyer id auction closing_ date auction multi item for auction Possible Values true Char Description Length The customer s auction ID 64 The auction s close date in the following format HH MM SS 28 DD Mmm YY YY YY PST The number of items purchased in multi item auction payments 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 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 Mass Payment TABLE A 7 IPN and PDT Variables Mass Payment Variable Name masspay
73. t 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 name 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 x represents the number of the shopping cart detail item option PayPal appends the number of the item where x represents the 200 selection number of the shopping cart detail item e g x option selectionl option selection2 parent txn_ In the case of a refund reversal or canceled reversal this 19 id payment _ date variable contains the txn_id of the original transaction while txn_id contains a new ID for the new transaction Time Date stamp generated by PayPal in the following format 28 HH MM SS DD Mmm YY YYYY PST March 2008 Order Management Integration Guide IPN and PDT Variables aa Website Payments Standard Website Payments Pro and Refund Information TABLE A 4 IPN and PDT Variables Website Payments Standard Website Payments Pro and Refund Information Variable Possible Char Name Values Description Length payment Canceled_ The status of the payme
74. 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 METHOD post gt lt INPUT TYPE hidden NAME day VALUE 16 gt lt INPUT TYPE hidden NAME month VALUE 09 gt lt INPUT TYPE hidden NAME year VALUE 2006 gt lt INPUT TYPE hidden 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 50 March 2008 Order Management Integration Guide IPN and PDT Variables IPN and PDT variables are case sensitive All values are lowercase except those for payment status
75. uction Payments Item ID Item Title Shipping Amount gt Insurance Amount Auction Site Buyer ID Item URL 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 Counter Party Status Verified vs Unverified Address Status Confirmed vs Unconfirmed Sales Tax HHH HOBNRAAARAw Other Fields O Subject C Note Subscription Number Payment Type O Balance Impact Any transaction that affects account balance Save Cancel For details about these optional fields see Appendix B Downloadable History Logs 3 Click the Save button to preserve you choices for future downloadable history logs Order Management Integration Guide March 2008 45 E Transaction History and Reporting Tools Downloading History Understanding the Status and Life Cycle of Transactions Each row in a downloadable history log shows a transaction its status at the time of the download and its effect on your balance Various types of transaction statuses and scenarios can have a negative positive or neutral balance effect 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 Cleared or Uncleared When a pending payment such as an eCheck clears after the th
76. ud on page 26 e Using IPN with Multiple Currencies on page 28 e Dispute Notification and Downloadable Dispute Report on page 31 About IPN Instant Payment Notification consists of three parts 1 A customer pays you 2 PayPal POSTs FORM variables to a URL you specify that runs a program to process the variables 3 You validate the notification Order Management Integration Guide March 2008 first technical draft 23 Instant Payment Notification IPN Setting Up IPN FIGURE 3 1 How IPN Works Three General Steps Pay Customer Browser lt FORM METHOD POST ACTION https paypal com cgi bin webscr gt Your website re Y q IPN post to your program 7 e lt se Notification Validation 1 A customer payment or a refund triggers IPN This payment can be via Website Payments 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 clears fails or is denied 2 PayPal posts HTML FORM variables to a program at a URL you specify You can specify this URL either in your Profile or with the notify url variable on each transaction This post is the heart of IPN 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 When your server receives a n
77. ute 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 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 48 March 2008 Order Management Integration Guide Transaction History and Reporting Tools ES Reporting Disputed Transactions 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 of 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 Da
78. utton Activating IPN by Including the Notification URL in Programming Code You can activate IPN for specific payments by including a notification URL in the programming code that your website sends to PayPal when people pay you PayPal sends only IPNs related to payments that result from the code PayPal sends them to the URL that you specified in the code For example if you accept payments from different websites through one PayPal account you could include different notification URLs in your programming code to let each website receive IPNs only for its own payments Note Notifcation URLs that you include in programming code override the notification URL that you may have set in your account profile To learn how to include notification URLs in programming code e See the Name Value Pair API Developer Guide and Reference e See the Website Payments Standard Integration Guide Setting Up an IPN Processing Program The data sent to you by IPN comes as HTML FORM name value pairs Sample code for the following development environments is available on the PayPal website at http www paypal com us cgi bin webscr emd p pdn ipn codesamples pop outside e ASP Net C e ASP VBScript Order Management Integration Guide March 2008 first technical draft 25 26 Instant Payment Notification IPN Using IPN Notification Validation to Help Prevent Fraud e ColdFusion e Java JSP e Perl e PHP Using IPN Notification Valid
79. ve only for txn_type subscr modify Time Date stamp generated by PayPal in the following format HH MM SS DD Mmm Y Y YYYY PST 64 March 2008 Order Management Integration Guide IPN and PDT Variables al Subscriptions TABLE A 1 Subscriptions Variables Possible Variable Values Description Char Limit periodl optional Trial subscription interval in days weeks months years example a 4 day interval is periodl 4 D period2 optional Trial subscription interval in days weeks months or years period3 Regular subscription interval in days weeks months or years amount 1 Amount of payment for trial period 1 for USD payments otherwise blank optional amount 2 Amount of payment for trial period 2 for USD payments otherwise blank optional amount 3 Amount of payment for regular subscription period for USD payments otherwise blank mc_amount1 Amount of payment for trial period 1 regardless of currency optional mc_amount2 Amount of payment for trial period 2 regardless of currency optional mc amount3 Amount of payment for regular subscription period regardless of currency mc currency See table of For non payment subscriptions IPNs i e supported txn type signup cancel failed eot or modify currencies this is the currency of the subscription For payment IPNs it is the currency of the payment ie txn type subscr payment recurring Indicates whether regular rate recurs 1 is yes
80. y 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 URL of eBay Auction Item eBay Auction specific alphanumeri onl c 30 character limit alphanumeric onl 60 character limit alphanumeric os 30 character limit alphanumeric 20 character limit alphanumeric 256 character limit option name 2 option selectionl option selection2 76 March 2008 Order Management Integration Guide Downloadable History Logs Boo TABLE B 1 Fields and Values in Downloadable History Logs Payment Button Related IPN Field Name 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
81. ys 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 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 Order Management Integration Guide March 2008 49 4 Transaction History and Reporting Tools Reporting Disputed Transactions 5 Select the checkboxes next to each of the choices that you want the alias to have 6 Click the Save button 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

PayPal Order Management - 2008 Integration Guide

Contents

Download Pdf Manuals

Related Search

Related Contents