Order Management Integration Guide
For Professional Use Only
Currently only available in English.
A usage Professional Uniquement
Disponible en Anglais uniquement pour l'instant.
Last Updated: October 2006
PayPal Order Management Integration Guide
Document Number: 100009.en_US-200608
© 2006 PayPal Inc. All rights reserved. PayPal and the PayPal logo are registered trademarks of PayPal Inc. Other trademarks and brands are the
property of their respective owners.
The information in this document belongs to PayPal Inc. It may not be used, reproduced or disclosed without the written approval of PayPal Inc.
PayPal (Europe) Ltd. is authorised and regulated by the Financial Services Authority in the United Kingdom as an electronic money in stitution.
PayPal FSA Register Number: 226056.
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 . P a yPal Inc. assumes no liability for damages (whether direct or indirect), caused by errors
or omissions, 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.
PayPal Inc. does not guarantee that the features described in this document will be announced or made available to anyone in the future.
Contents
Chapter P Preface . . . . . . . . . . . . . . . . . . . . . . . . . . .11
This Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Organization of This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Notational Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Documentation Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . .15
Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Differences between Instant Payment Notification (IPN) and Payment Data Transfer (PDT) 16
SSL Not Required for IPN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
PayPal-Supported Transactional Currencies . . . . . . . . . . . . . . . . . . . . . . . . 17
Chapter 2 Payment Data Transfer . . . . . . . . . . . . . . . . . . . 19
How PDT Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Enabling Payment Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Getting and Using the Identity Token . . . . . . . . . . . . . . . . . . . . . . . . . . 24
PDT Notification Synch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Constructing the POST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
PayPal Response to POST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
PDT and Auto Return: Messaging to Buyer . . . . . . . . . . . . . . . . . . . . . . . 26
Preventing Fraud. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Chapter 3 Instant Payment Notification (IPN) . . . . . . . . . . . . .29
About IPN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Setting Up IPN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Activating IPN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Setting Up an IPN-Processing Program . . . . . . . . . . . . . . . . . . . . . . . . . 31
Order Management Integration Guide October 2006 3
Contents
IPN Notification Validation: Preventing Fraud . . . . . . . . . . . . . . . . . . . . . . . . 31
Shared Secret Per Transaction or by Profile Setting . . . . . . . . . . . . . . . . . . 32
Shared Secret Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Your HTTPS Postback to PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Using IPN with Multiple Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
mc_gross and mc_fee . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
mc_currency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
payment_gross and payment_fee . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Examples of Multi-currency IPN Variables. . . . . . . . . . . . . . . . . . . . . . . . 35
Chapter 4 Transaction History and Reporting Tools . . . . . . . . . . 39
Monthly Account Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Online History Searching. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Basic Search: Time Periods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Advanced Search: Key Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Download My History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Choosing a Date Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Selecting a File Format and Transaction Categories . . . . . . . . . . . . . . . . . . 42
Completed Transactions Since Last Download . . . . . . . . . . . . . . . . . . . . . 43
Customizing the Download: Selecting Transaction Fields. . . . . . . . . . . . . . . . 43
Transaction Reconciliation with the Balance Impact Column . . . . . . . . . . . . . . 45
Lifecycle of a Transaction: Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Net Amount Column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Dispute Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Programmatic Access to Dispute Report . . . . . . . . . . . . . . . . . . . . . . . . 47
Appendix A IPN and PDT Variables . . . . . . . . . . . . . . . . . . . . 51
About These Tables of Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Transaction-Specifc Variable Values. . . . . . . . . . . . . . . . . . . . . . . . . . . 51
test_ipn Variable in Sandbox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
IPN Variables in All Posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
IPN Version: notify_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Security Information: verify_sign. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Buyer Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Basic Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Advanced and Custom Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Website Payments Standard and Refund Information . . . . . . . . . . . . . . . . . . . . 55
Currency and Currency Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
4 October 2006 Order Management Integration Guide
Contents
Auctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Mass Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Subscriptions Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Dispute Notification Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
PDT-Specific Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Appendix B Downloadable History Log
Columns and Values71
Appendix C Country Codes . . . . . . . . . . . . . . . . . . . . . . . 79
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Order Management Integration Guide October 2006 5
Contents
6 October 2006 Order Management Integration Guide
List of Tables
Table P.1 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Table 1.1 PayPal-Supported Currencies and Currency Codes for Transactions . . . 17
Table 4.1 Online Search: Selectable Activity Types . . . . . . . . . . . . . . . . . 41
Table 4.2 Advanced Transaction Search: Key Fields . . . . . . . . . . . . . . . . . 41
Table A.1 IPN and PDT Variables: Buyer Information. . . . . . . . . . . . . . . . . 52
Table A.2 IPN and PDT Variables: Basic Information . . . . . . . . . . . . . . . . . 53
Table A.3 IPN and PDT V ariables: Advanced and Custom Information. . . . . . . . 54
Table A.4 IPN and PDT Variables: Website Payments Standard and Refund Information
55
Table A.5 IPN and PDT Variables: Currency and Currency Exchange Information . . 60
Table A.6 IPN and PDT Variables: Auctions. . . . . . . . . . . . . . . . . . . . . . 61
Table A.7 IPN and PDT Variables: Mass Payment . . . . . . . . . . . . . . . . . . 62
Table A.8 Subscriptions Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Table A.9 IPN Variables with Each Subscription Event . . . . . . . . . . . . . . . . 65
Table A.10 Dispute Notification Variables. . . . . . . . . . . . . . . . . . . . . . . . 68
Table A.1 1 PDT-Specific Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Table B.1 Downloadable History Log Columns and Values . . . . . . . . . . . . . . 71
Table 1: Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Order Management Integration Guide October 2006 7
List of Tables
8 October 2006 Order Management Integration Guide
List of Figures
Figure 3.1 How IPN Works: Three General Steps . . . . . . . . . . . . 30
Figure 4.1 The History Page . . . . . . . . . . . . . . . . . . . . . . 39
Figure 4.2 Download My History . . . . . . . . . . . . . . . . . . . . 42
Figure 4.3 Customize My History Download . . . . . . . . . . . . . . . 44
Figure 4.4 Gross, Fee and Net Amount Calculations from History Log . . . 46
Figure 4.5 Dispute Report . . . . . . . . . . . . . . . . . . . . . . . 47
Order Management Integration Guide October 2006 9
List of Figures
10 October 2006 Order Management Integration Guide
Preface
P
This Document
This release of the PayPal Order Management Integration Guide, a document that describes
the PayPal features for managing orders, such as Payment Data Transfer (PDT), Instant
Payment Notification (IPN), and Downloadbale History Log, replaces the version released in
December, 2005.
This document replaces portions of the Merchant User Manual and Integration Guide issued in
April, 2005.
Intended Audience
This document is written for merchants who use PayPal to manage order information.
Organization of This Document
Chapter 1, “Introduction,” gives a brief overview of the PayPal features for order management
discussed in this guide.
Chapter 2, “Payment Data Transfer,” describes how PDT works and how to set it up.
Chapter 3, “Instant Payment Notification (IPN),” describes how IPN works and how to set it
up.
Chapter 4, “Transaction History and Reporting Tools,” describes monthly account statements,
online transaction search, the Downloadable History Log, and dispute reports.
Appendix A, “IPN and PDT Variables,” is a detailed description of all variables and values
returned by IPN or PDT.
Appendix B, “Downloadable History Log Columns and Values,” describes the columns and
values that can be included in the Downloadable History Log.
Order Management Integration Guide October 2006 11
Preface
Notational Conventions
Notational Conventions
This document uses typefaces to identify the characteristics of text. These typefaces and the
characteristics they imply are described below:
Typeface How Used
serif italics A document title.
A term being discussed or defined.
For example: A file is a readable or writable stream of characters …
Boolean values (not keywords).
For example: The function returns true if it encounters an error.
monospaced Pathnames or file names that appear in body text frames.
Code-related names that appear in body text frames. Such names are used for
functions, callbacks, arguments, data structures, and fields.
For example: AbstractResponseType is the SOAP response type definition on
which all PayPal API response methods are based.
Components of Internet protocol requests and responses, such as HTTPS and
FORM variables.
For example: The PayPal system uses a method=POST request to return IPN
status variables related to subscriptions, such as txn_type.
Serif bold User interface names, such as window names or menu selections.
For example: On the Profile page, click Email to confirm your email address.
San-serif
oblique
Placeholders used in the context of a format or programming standard or formal
descriptions of PayPal system syntax. Placeholders indicate values or names that
the reader should provide.
Example: For example, amount is the variable for a single-item shopping cart, but
amount_
is the item amount for the third item in a multiple-item shopping cart.
X is the name of the variable for a multi-item shopping cart. amount_3
To convey additional information, this document may also apply color and underlining to
words or phrases that use the typefaces described above. Such use is described below:
Text attribute How Used
xxxxxx Hypertext link to a page in the current document or to another document in the set.
xxxxxx
Hypertext link to a URL or that initiates a web action, such as sending mail.
12 October 2006 Order Management Integration Guide
Documentation Problems
If you discover any errors in or have any problems with this documentation, please email us by
following the instructions below. Describe the error or problem as completely as possible and
give us the document title, the date of the document (located at the foot of every page), and the
page number or page range.
To contact Customer Service about documentation problems:
Preface
Documentation Problems
1. Go to
https://www.paypal.com/.
2. Click Help in the upper left corner of the page.
3. Click Contact Us in the lower left of the page.
4. Choose Help by Email.
5. Complete the form.
Revision History
Revision history for PayPal Order Management Integration Guide.
TABLE P.1 Revision History
Date Description
October 2006 Details about the Downloadable Dispute Report. Minor additions and
July 2006 Minor correction to values of payment_status IPN variable.
May 2006 Description of the programmatically retrievable Disput Report. Additional IPN
corrections to some variables in Appendix A.
variable values for txn_type: merch-pmt for the Website Payments Pro monthly
fee and adjustment for a resolved dispute requiring a chargeback.
October 2006 Adaptation to specifics for Germany.
Order Management Integration Guide October 2006 13
Preface
Revision History
14 October 2006 Order Management Integration Guide
1
Introduction
PayPal offers four payment notification methods for backend integration:
z Email
z Reporting Tools
z Instant Payment Notification (IPN)
z Payment Data Transfer (PDT)
You will receive an email notification in the following cases:
z Successful Payment
z Pending Payment
z Cancelled Payment
If you do not want to receive payment notifications via email:
1. Click the Profile subtab of the My Account tab.
2. Click the Notifications link in the Account Information column.
3. Find the Payment Notifications heading and clear the I receive PayPal Website
4. Click Save.
Reporting
PayPal’s Reporting Tools provide you with the information you need to effectively measure
and manage your business. With PayPal’s Reporting Tools, you can:
z Analyze your revenue sources to better understand your customers’ buying behavior
z Automate time-consuming bookkeeping tasks
z Accurately settle and reconcile transactions
Available reports:
Payments and Instant Purchase checkbox.
z Monthly Account Statements: View a summary of all credits and debits that have affected
your account balance each month.
Order Management Integration Guide October 2006 15
Introduction
Differences between Instant Payment Notification (IPN) and Payment Data Transfer (PDT)
z Merchant Sales Reports:
– Settlement Report (STL): Contains only the records of all balance-effecting daily
transactions. Can be coordinated with Settlement System or created independently of the
moving of money.
– Transactions Detail Report (TDR): Status of all transactions (including non-complete
transactions such as eCheck) in the account in a 24 hour period. A super set of data
contained in Settlement Report including buyer and auction data.
– Order Report (ODR): List all orders created in a 24-hr period wit h the order ID. Only
appropriate for those merchants using the order functionality on their website.
– Dispute Resolution Report (DRR): List all cases that changed in status or were created
in a 24-hr period. Allows a merchant to reconcile cases against money moving
transactions.
z History Log: View an online record of your received and sent payments.
z Downloadable Logs: Keep track of your transaction history by downloading it into
various file formats (suitable for financial settlements).
For more information about PayPal's reports, see
bin/webscr?cmd=p/xcl/rec/reports-intro-outside.
http://www.paypal.com/cgi-
Differences between Instant Payment Notification (IPN) and
Payment Data Transfer (PDT)
PDT's primary function is to display payment transaction details to buyers when they are
automatically redirected back to your site upon payment completion; however, there are cases
where you will not receive notification of all transactions, such as with pending transactions,
refunds, and reversals. For these reasons, or if you are using this data to fulfill orders, PayPal
strongly recommends that you also enable Instant Payment Notification (IPN).
Both IPN and PDT send back the same data; however, there are several important differences.
PDT:
z Requires Auto Return to be enabled.
z Auto Return will include an ID that can be used to query PayPal for the complete
transaction details.
z It is possible to miss a notification if the user closes the browser before the redirection is
complete.
IPN:
z Does not require Auto Return to be enabled.
z At the end of the website payment flow, PayPal POSTs the IPN data asynchronously (i.e.
not as part of the website payment flow).
z IPNs will also POST for EFT completions, reversals, and refunds.
16 October 2006 Order Management Integration Guide
PayPal-Supported Transactional Currencies
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.
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
Introduction
CHF Swiss Franc
CZK Czech Koruna
DKK Danish Krone
EUR Euro
GBP Pound Sterling
HKD Hong Kong Dollar
HUF Hungarian Forint
JPY Japanese Yen
NOK Norwegian Krone
NZD New Zealand Dollar
PLN Polish Zloty
SEK Swedish Krona
SGD Singapore Dollar
USD U.S. Dollar
Order Management Integration Guide October 2006 17
Introduction
PayPal-Supported Transactional Currencies
18 October 2006 Order Management Integration Guide
Payment Data Transfer
2
Payment Data Transfer (PDT) provides merchants with the ability to display transaction
details to buyers who are redirected back to their site upon payment completion.
NOTE: You must enable Auto Return for Website Payments to use Payment Da ta Transfer.
Auto Return brings your buyers back to your website immediately after payment
completion. Auto Return applies to PayPal Website Payments, including Buy Now,
Donations, Subscriptions, and Shopping Cart. For more information about Auto
Return, see the PayPal Website Payments Standard Integration Guide
How PDT Works
Bob is going to purchase a widget from the Widget Warehouse.
Step 1: Bob goes to the Widget Warehouse website, finds the widget he wants, and clicks Buy
Now.
.
Order Management Integration Guide October 2006 19
Payment Data Transfer
How PDT Works
Step 2: Bob is taken to a PayPal Payment Details page which displays the details of the
payment he is about to make.
Step 3: Bob enters his PayPal account information into the PayPal Login fields.
20 October 2006 Order Management Integration Guide
Payment Data Transfer
How PDT Works
Step 4: Bob is then taken to a confirmation page that displays the details of his selection,
information about how his automatic payments will be funded, and his shipping information.
He clicks Pay to complete the payment.
Order Management Integration Guide October 2006 21
Payment Data Transfer
How PDT Works
Step 5: A payment confirmation page appears that informs Bob that his payment has been
completed and that he is being redirected back to the Wi dget Warehouse website.
Step 6: A transaction token is passed to the return URL provided by the Widget Warehouse.
The Widget Warehouse fetches the transaction token and retrieves the transaction details from
PayPal via an HTTP POST. Included in the HTTP post is the identity token that was given to
the Widget Warehouse when PDT was enabled.
For more information about the PDT identity token, see “Getting and Using the Identity
Token” on page 24. For more information about the HTTP POST, see “PDT Notification
Synch” on page 25.
Step 7: The Widget Warehouse's Thank You page appears and displays the transaction
information, again informing Bob that his transaction has been completed and a receipt for the
purchase has been emailed to him. The page also displays payment details, a link to PayPal
that Bob can use to view more transaction details if necessary, as well as links that he can use
to continue shopping.
22 October 2006 Order Management Integration Guide
Payment Data Transfer
Enabling Payment Data Transfer
For example, 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
Step 8: Bob receives an email receipt for this transaction, confirming his purchase and
including a copy of the payment details, the W idget Warehouse's business information, and his
confirmed shipping address.
www.paypal.com to view details of this transaction.
Enabling Payment Data Transfer
To enable PDT:
1. Click the My Account tab.
2. Click the Profile subtab.
Order Management Integration Guide October 2006 23
Payment Data Transfer
Enabling Payment Data Transfer
3. Click the Website Payment Preferences link, as shown in the following snapshot.
The Website Payment Preferences page opens.
4. Click the Payment Data Transfer On radio button, as shown in the following diagram.
You must enable Auto Return in order to use Payment Data Transfer. Auto Return can also
be enabled from the Website Payment Preferences page.
5. Click Save.
Getting and Using the Identity Token
When you click Save and save your PDT preferences, a message appears at the top of the page
indicating that you have successfully saved your preferences. Your identity token also appears
in this message.
24 October 2006 Order Management Integration Guide
Payment Data Transfer
PDT Notification Synch
You will need to pass this identity token, along with the transaction token, to PayPal in order to
receive information that confirms that a payment is complete.
For security, the identity token is not sent to you; however, once you have enabled PDT, it
permanently appears below the Payment Data Transfer On/Off radio buttons on the Website
Payments Preferences page.
PDT Notification Synch
After you have activated PDT, every time a buyer makes a website payment and is redirected
to your return URL, a transaction token is sent via a FORM GET variable to this return URL.
To properly use PDT and display transaction details to your customer, you should read the
transaction token from the variable tx and retrieve transaction details from PayPal by
constructing an HTTPS POST to PayPal. This is called notification synch or synchronization.
Constructing the POST
Here are the guidelines for constructing the PDT HTTPS POST to PayPal for notification
synch:
1. Your POST must be sent to
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:
value_of_transaction_token
tx=
https://www.paypal.com/cgi-bin/webscr.
4. You must post your identity token using the variable at and the value of your PDT identity
token:
your_identity_token
at=
Order Management Integration Guide October 2006 25
Payment Data Transfer
PDT Notification Synch
For information about the identity token, see “Getting and Using the Identity Token” on
page 24.
PayPal Response to POST
PayPal responds to the post with a single word on one line in the body of the response:
SUCCESS or FAIL. When you receive a SUCCESS response, the rest of the body of the
response is the transaction details, one per line, in the format
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%40hot mail.com
payment_gross=3.99
mc_currency=USD
custom=For+the+purchase+of+the +rare+book+Green+E ggs+%26+Ham
...
key=value where key and value
If the response is FAIL, PayPal recommends making sure that:
z The Transaction token is not bad.
z The ID token is not bad.
z The tokens have not expired.
PDT and Auto Return: Messaging to Buyer
When Auto Return, you must display a message on the page displayed by the Return URL that
helps the buyer understand that the payment has been made, that the transaction has been
completed, and that payment transaction details will be emailed to the buyer. You can display
to your customer whatever payment details you feel are appropriate; however, PayPal
recommends including the following:
z Item name
z Amount paid
z Payer email
z Shipping address
If you are using PDT to determine when to fulfill an order automatically, confirm that the
payment_status is Completed, since the buyer could use methods such as EFT that do not
immediately clear.
For a list of PDT variables, see Appendix A, “IPN and PDT Variables.”
26 October 2006 Order Management Integration Guide
Preventing Fraud
In order to prevent fraud, PayPal recommends that your programs verify the following:
z txn_id is not a duplicate to prevent someone from reusing an old, completed transaction.
z receiver_email is an email address registered in your PayPal account, to prevent the
payment from being sent to a fraudulent account.
z Other transaction details, such as the item number and price, to confirm that the price has
not been changed.
Code Samples
PayPal has made available code samples that you can use to set up PDT. These samples are
available at
There are code samples for the following development environments:
https://www.paypal.com/us/cgi-bin/webscr?cmd=p/xcl/rec/pdt-code.
Payment Data Transfer
Preventing Fraud
z ASP/VBScript
z ColdFusion
z PERL
z PHP
Order Management Integration Guide October 2006 27
Payment Data Transfer
Code Samples
28 October 2006 Order Management Integration Guide
3
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:
z “About IPN” on page 29
z “Setting Up IPN” on page 30”
z “IPN Notification Validation: Preventing Fraud” on page 31”
z “Using IPN with Multiple Currencies” on page 34”
About IPN
Instant Payment Notification consists of three parts:
Instant Payment Notification (IPN)
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 October 2006 29
Instant Payment Notification (IPN)
Setting Up IPN
FIGURE 3.1 How IPN Works: Three General Steps
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 completes, fails, or is denied.
2. PayPal posts HTML FORM variables to a program at a URL you specify. You can specify
this URL either in your Profile or with the notify_url variable on each transaction. This
post is the heart of IPN. Included in the notification is the customer’s payment information
(such as customer name, payment amount). All possible variables in IPN posts are detailed
in this guide. When your server receives a notification, it must process the incoming data.
3. Your server must then validate the notification to ensure that it is legitimate.
Setting Up IPN
Setting up IPN has two parts:
1. Activating IPN for your PayPal account
2. Setting up a program on your website to process the IPN FORM variables
Activating IPN
To activate IPN, you can either change a setting in your PayPal Profile or include the
notify_url variable in the payment FORMs on your website.
Profile Setting
1. Log in to your Business or Premier PayPal account.
30 October 2006 Order Management Integration Guide
2. Click the Profile subtab.
3. Under Selling Preferences, click Instant Payment Notification Preferences.
4. Click Edit.
5. Click the checkbox and enter the URL of the program that will process the IPN posts.
6. Click Save.
notify_url
Alternatively, you can activate IPN by including the notify_url variable in your PayPal button
HTML. This field specifies the URL of a program that can process the IPN. For more details,
see “IPN Notification Validation: Preventing Fraud” on page 31.
Setting Up an IPN-Processing Program
The data sent to you by IPN is in the form of HTML FORM name/value pairs. At a minimum,
your program must process these pairs. What other processing might be required depends on
your order management needs, what kinds of database you use, and other factors outside the
scope of this guide.
Instant Payment Notification (IPN)
IPN Notification Validation: Preventing Fraud
Code samples for the following development environments are available on the PayPal
website at
z ASP.Net/C#
z ASP/VBScript
z ColdFusion
z Java/JSP
z Perl
z PHP
http://www.paypal.com/de/cgi-bin/webscr?cmd=p/xcl/rec/ipn-code-outside:
IPN Notification Validation: Preventing Fraud
After your server receives Instant Payment Notification, you must confirm that you received
it. This is known as notification validation, which is a means for PayPal to help you prevent
spoofing or “man-in-the-middle” attacks.
IMPORTANT: If you do not use Encrypted Website Payments (EWP) or shared secret
validation, you must check the price, transaction ID, PayPal receiver email
address and other data sent to you by IPN to ensure that they are correct. By
examining these the data you can be sure that you are not being spoofed.
You have two methods by which you can validate the notification:
Order Management Integration Guide October 2006 31
Instant Payment Notification (IPN)
IPN Notification Validation: Preventing Fraud
1. Sending a shared secret that only you know, described in “Shared Secret Validation” on
page 32. PayPal recommends this method because it ensures the validity of the data and
decreases network traffic to and from your website. Shared secret validation is appropriate:
– if you are not using a shared website hosting service.
– if you have enabled SSL on your web server.
– if you are using PayPal Encrypted Website Payments.
– if you use the notify_url variable on each individual payment transaction.
2. Sending a POST back to PayPal after you receive the IPN and verify the correctness of the
data, described in “Your HTTPS Postback to PayPal” on page 33. Postback is appropriate:
– if you rely on a shared website hosting service
– if you do not have SSL enabled on your web server
Both methods rely on the concept of a notification URL, which is described in the next
section.
Shared Secret Per Transaction or by Profile Setting
The URL to which PayPal posts IPN data is called the notification URL. It can be set either
with each individual payment transaction or globally in your Profile for all transactions:
z Per Transaction: If you want to receive payment notifications for different payments at
different URLs (for example, if you need to separate payments to different websites you
run), use the notify_url variable to pass the notification URL. With each payment PayPal
saves the value of the notify_url for a specific payment, and any subsequent updates to
that payment (such as a cleared eCheck) are sent to that notify_url. When you pass a
notify_url in your post, it overrides the setting in your Profile.
NOTE: The value of notify_url must be URL-encoded.
z Profile Setting. If you want to receive your IPNs at only a single URL, enter that URL in
the Preferences section of your Profile.
Likewise, the shared secret you can use to validate that you have received an IPN can be set
either with each individual payment transaction or globally in your Profile for all transactions:
z Per Transaction: If you want a distinct shared secret for each notification for each
payment, append a FORM variable name and a shared secret value to the value of the
notify_url variable. When you pass a shared secret in your payment post, it overrides
the setting in your Profile.
z Profile Setting. If you want the same shared secret for each and every transaction, enter
that shared secret in the Preferences section of your Profile.
Shared Secret Validation
The recommended method for notification validation is to use a shared secret on individual
payment transactions. Add a shared secret variable and value to the value of the notify_url
32 October 2006 Order Management Integration Guide
Instant Payment Notification (IPN)
IPN Notification Validation: Preventing Fraud
variable to which the IPN data is posted after a payment is made. The shared secret consists of
the following:
notify_url=yourIPNnotificationURL?shared_secret_variable_name=shared_secret_value
where:
yourIPNNotificationURL is a URL on your website at which you want to receive notification.
shared_secret_variable_name is any variable name you want.
shared_secret_value is the shared secret itself.
For example, the value of notify_url variable might look like this:
notify_url=https%3A//www.mysit e.com/PP-IPN-Valid ate.cfm?secret=shhhhhhh
Security Considerations with Shared Secret Validation
To ensure the security of your shared secret, you should use Encrypted Website Payments
(EWP). For information about EWP, see the PayPal Website Payments Standard Checkout
Integration Guide.
The value of the shared secret is not encrypted; it is in clear text for easier processing.
Therefore, the shared secret value is recorded in your web server’s access log. Be sure to
practice proper security for your server access logs. If you use a web server hosting service,
ensure that your provider practices proper security of your data.
NOTE: Your notification URL should check the validity of the returned shared secret and flag
for investigation any transaction that does not have the correct shared secret.
You r HTTPS Postback to PayPal
The second method for validating your receipt of an IPN is to post back to PayPal the exact
variables and values you received in the IPN.
Constructing the POST
Here are the guidelines for constructing the IPN HTTPS POST to PayPal for notification
validation.
NOTE: You can implement IPN without SSL, but PayPal recommends against doing so.
1. Your POST must be sent to
2. You must include the variable cmd with the value _notify-validate:
cmd=_notify-validate
3. You must post all the form variables you received exactly as you received them.
PayPal Response to Postback
PayPal responds to the postback with a single word in the body of the response: VERIFIED or
INVALID.
https://www.paypal.com/cgi-bin/webscr.
When you receive a VERIFIED response, perform the following checks:
Order Management Integration Guide October 2006 33
Instant Payment Notification (IPN)
Using IPN with Multiple Currencies
1. Check that the payment_status is Completed.
2. If the payment_status is Completed, check the txn_id against the previous PayPal
transaction you have processed to ensure it is not a duplicate.
3. After you have checked the payment_status and txn_id, make sure the
receiver_email is an email address registered in your PayPal account.
4. Check that the price, mc_gross, and currency, mc_currency, are correct for the item,
item_name or item_number.
5. Check the the shared secret returned to you is correct.
Once you have completed the above checks, you can update your database based on the
information provided.
If you receive an INVALID response, you should investigate. In some cases, this response is
caused by an IPN error, possibly from a change in the IPN format. To determine if it is an IPN
error, first examine your code. If you need further assistance, go to
click the Seller Tools topic, and click Instant Payment Notification (IPN).
http://www.paypal.com/wf/,
Using IPN with Multiple Currencies
With multiple currencies, you can accept payments in any of the PayPal-supported currencies
(see “PayPal-Supported Transactional Currencies” on page 17). As a result, your IPNs will
then include information about the currency of the payment. The following overview explains
how IPN interacts with multiple currencies.
NOTE: If you are using one of PayPal’s Website Payments solutions (e.g. PayPal Shopping
Cart), and would like to be paid in a currency other than Euro, you will need to set up
your buttons for your currency of choice.
mc_gross and mc_fee
These variables reflect the amount received and corresponding fee of your payments. In order to
see those variables IPN has to use thepayment_gross variable.
z mc_gross:Full amount of payment received, before transaction fee.
z mc_fee: Transaction fee associated with the payment.
NOTE: mc_fee is not always present in IPNs, such as when a payment is pending.
z For subscription IPNs, such as signup, cancel, modify, failed, and eot, mc_currency is the
currency of the subscription, rather than the currency of the payment.
NOTE: The variables mc_gross and mc_fee will not be added to IPNs with txn_type:
subscr_signup, subscr_cancel, subscr_modify, subscr_failed
subscr_eot
34 October 2006 Order Management Integration Guide
.
, or
mc_currency
This variable reflects the currency of mc_gross, mc_fee, payment_gross, and payment_fee amounts.
Possible values are detailed in “PayPal-Supported Transactional Currencies” on page 17.
payment_gross and payment_fee
These variables reflect the amount received and corresponding fee of US Dollar (USD)
payments. If the amount received and fee deducted are in a currency other than USD, the
variables will still appear in your IPN, but will have no values in them.
Examples of Multi-currency IPN Variables
Example 1
If a user with a EUR balance receives a €100 EUR payment, the following variables will be
used for the payment:
z mc_gross and mc_fee have values.
Instant Payment Notification (IPN)
Using IPN with Multiple Currencies
z payment_gross and payment_fee are blank.
EXAMPLE 3.1 Multi-currency IPN: EUR Payment
payment_status = Completed
payment_gross =
payment_fee =
mc_gross = 100
mc_fee = 3.00
mc_currency = EUR
Example 2
f a user with a USD balance receives a $100 USD payment, the following variables will be
used for the payment:
z mc_gross = payment_gross
z mc_fee = payment_fee
EXAMPLE 3.2 Multi-currency IPN: USD Payment
payment_status = Completed
payment_gross = 100
payment_fee = 3.00
mc_gross = 100
mc_fee = 3.00
mc_currency = USD
Order Management Integration Guide October 2006 35
Instant Payment Notification (IPN)
Using IPN with Multiple Currencies
Example 3
If the account is set to automatically convert payments, these variables will be used to show
the conversion. This example is for a user with a EUR balance who receives a payment of 100
GBP:
EXAMPLE 3.3 Mutli-currency IPN: Auto matic Con version of GBP Pa yment
payment_status = Completed
payment_gross =
payment_fee =
mc_gross = 100
mc_fee = 3.00
mc_currency = GBP
settle_amount = 145.5
settle_currency = EUR
exchange_rate = 1.5
Example 4
If a payment received is pending due to pending_reason = multi_currency, the first IPN
received would not have the settle_amount, settle_cu rrency, or exchange_rate.
EXAMPLE 3.4 Mutli-currency IPN: Pending Pay me nt
payment_status = Pending
pending_reason = multi_currenc y
payment_gross = mc_gross = 100
mc_currency = GBP
The second IPN contains information about settling the payment. If the payment is accepted
into the account’s primary currency, which is EUR in the following example:
EXAMPLE 3.5 Pending - Convert to Primary Curre ncy
payment_status = Completed
payment_gross =
payment_fee =
mc_gross = 100
mc_fee = 3.00
mc_currency = GBP
settle_amount = 145.5
settle_currency = EUR
exchange_rate = 1.5
If the payment is accepted into a balance of the same currency:
EXAMPLE 3.6 Pending - Accept to Curren cy Balance
payment_status = Completed
payment_gross =
payment_fee =
mc_gross = 100
mc_fee = 3.00
36 October 2006 Order Management Integration Guide
Instant Payment Notification (IPN)
Using IPN with Multiple Currencies
mc_currency = GBP
If the payment is denied:
EXAMPLE 3.7 Pending - Denied
payment_status = Denied
payment_gross =
mc_gross = 100
mc_currency = GBP
NOTE: If a user receives a payment into a currency balance and later converts this amount into
another currency balance, the corresponding currency conversion transaction has no
IPN.
Order Management Integration Guide October 2006 37
Instant Payment Notification (IPN)
Using IPN with Multiple Currencies
38 October 2006 Order Management Integration Guide
4
Transaction History and
Reporting Tools
With transaction history and reporting tools, you can access monthly account statements,
search specific time periods for transaction records or customer disputes, and download these
search results to your local computer.
To access these features:
1. Log in to your PayPal Business or Premier account.
2. Click the History subtab.
The History page is shown in Figure 4.1, “The History Page.”
FIGURE 4.1 The History Page
Monthly Account Statements
After you activate this feature, you can view
Order Management Integration Guide October 2006 39
Transaction History and Reporting Tools
Online History Searching
monthly account statements of your transaction records. New statements become available on
the 15th of each month, and the statements are retained online for up to three months.
To activate monthly account statements:
1. Click Get Monthly Account Statements on the History page.
2. On the displayed page, click the Yes radio button.
3. Click Save.
Online History Searching
The History page gives you many options for searching the transaction records viewable
online.
There are two types of searches: basic and advanced.
z With basic search, you specify the date range and type of activity you’re interested in.
z With advanced search, you specify the date range and a pattern you want to find in certain
fields of the transaction records.
Basic Search: Time Periods
You have two ways to narrow the search.
1. You can select a pre-determined date range:
–The Past Day
– The Past Week
– The Past Month
–The Past Year
2. You can select an exact From and To range of day, month, and year.
40 October 2006 Order Management Integration Guide
Transaction History and Reporting Tools
Online History Searching
IMPORTANT: The length of time of the date range affects how quickly you see the results.
The longer the time, the slower the search. For the speediest results, try to
make the range as narrow as possible.
Basic Search: Activity Types
The default set of transactions (also called “activities”) is All Activity- Simple View. The
selectable activity types are listed in Ta ble 4.1, “Online Search: Selectable Activity Types.”
TABLE 4.1 Online Search: Selectable Activity Types
All Activity -Advanced
View
All Activity Simple
View
Payments Sent or
Received
Mass Payments Refunds eChecks
Money Requests Currency Conversions Preapproved Payments
Funds Added or
Withdrawn
Fee Reversals Open Authorizations:
Subscriptions Shipping PayPal Buyer Credit
BillPay Transactions Balance Affecting
Balance Transfer Gift Certificates
All Activity - Advanced View is the same as All Activity - Simple View except it also
includes a Balance column. The Balance column can show “...” in some instances, which
indicates that showing a balance is not appropriate for these kinds of transaction.
Advanced Search: Key Fields
For an advanced search, specify the dates in the same manner as you do for basic search, as
detailed in “Basic Search: Time Periods” on page 40.
Sent or Received
Transactions
You can limit your search to the following fields.
T
ABLE 4.2 Advanced Transaction Search: Key Fields
Field Matching Criteria
Email The text you enter must exactly match an email address.
Transaction ID Exact match.
Last Name Any part of the text you enter can match. For example, the
text mit matches Smith and Mitty.
Last Name, First Name Any part of text can match.
Receipt ID Exact match.
Item Number Exact match.
Order Management Integration Guide October 2006 41
Transaction History and Reporting Tools
Download My History
Download My History
Download My History gives you many options for selecting the transactions and fields to
save to your local computer.
To access the Download My History page:
1. In the upper right corner of the History page, click Download My History.
FIGURE 4.2 Download My History
Choosing a Date Range
To download your history, specify the dates in the same manner as you do for basic search, as
detailed in “Basic Search: Time Periods” on page 40.
Selecting a File Format and Transaction Categories
You can choose among four file formats. Each file format can include all activity, but the
comma-delimited and tab-delimited formats are limited to either completed or balanceaffecting payments.
1. Comma-delimited:
42 October 2006 Order Management Integration Guide
Transaction History and Reporting Tools
– All activity
– Completed payments
– Balance-affecting payments
2. Tab-delimited:
– All activity
– Completed payments
– Balance-affecting payments
3. Intuit Quicken (.qif file format)
4. Intuit QuickBooks (.iif file format)
Completed Transactions Since Last Download
You can use the Last Download to Present feature to coincide with your consecutive
accounting periods. It includes only completed transactions in either comma-delimited or tabdelimited format.
Download My History
Customizing the Download: Selecting Transaction Fields
You can also include any of the fields shown in Figure 4.3, “Custo mize My History
Download” on page 44. Which of these fields you include in the downloaded file depends on
what you want to do with the downloaded data.
The transaction history always contains the default fields listed below. The meanings of these
fields are described in Appendix B, “Downloadable History Log Columns and Values.”
z Date, Time, and Timezone
z Name
z Type, Status and Currency
z Gross, Fee, and Net
z From Email Address and To Email Address
z Transaction ID and Reference Transaction ID
z Receipt ID
z Balance
Order Management Integration Guide October 2006 43
Transaction History and Reporting Tools
Download My History
FIGURE 4.3 Customize My History Download
44 October 2006 Order Management Integration Guide
Transaction History and Reporting Tools
Transaction Reconciliation with the Balance Impact Colu mn
The Balance Impact column shows the word “Credit” for a positive effect or the word “Debit”
for a negative effect on your PayPal account balance.
Credit
When you receive an instant payment or credit card transaction, the Balance Impact column
indicates a credit. Other possible credits to your account are refunds, reversals and payments
sent but never claimed.
In some cases, a credit line-item can update a debit for a transaction.. For example, if you send
a payment initially indicated as a debit, but it is denied by the recipient, a new line-item for
that transaction will indicate a credit.
Debit
Debits are transactions that reduce your available balance. For example, refunded transactions
are recorded as a debit in the Balance Impact column and as completed in the Status column.
Memo Entries
The Balance Impact column can display a Memo entry for transactions that do not affect your
balance, such as unclaimed or uncleared transactions. These kinds of transactions have no
impact on your balance since neither transaction ever becomes a completed transaction.
Download My History
Lifecycle of a Transaction: Status
Every transaction in your History Log shows the transaction a status at the time the data were
downloaded and its corresponding impact on your balance.
Various types of transaction statuses and scenarios can have a negative, positive, or neutral
balance impact. These statuses include:
z Pending
z Held
z Completed
z Denied
z Cancelled
z Reversed
For a complete list of possible transaction statuses, see “Status” on page 73.
Pending to Completed or Cancelled
When a pending payment, such as an EFT, completes after the he buyer has sent the money
from his bank, the transaction status changes from Pending to Completed.
Status of Disputed Transactions
Transactions with a Placed status (for temporary holds) usually involve a customer dispute.
Order Management Integration Guide October 2006 45
Transaction History and Reporting Tools
Dispute Report
If you are found in favor in a dispute, the transaction will be updated with a new line-item to
indicate a Credit. However, if the opposite is true, the Balance Impact column will not change
from the Debit status for that transaction.
You can generate a dispute report that correlates the transaction to the customer and the reason
for the dispute. For more information, see “Dispute Report” on page 46.
Net Amount Column
The Net Amount of a transaction can aid in faster reconciliation.
In most cases, the Net Amount is the Gross minus Fee. When a 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
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:
z 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.
z Chargeback: A buyer has filed a complaint with a credit card company that has resulted in
a chargeback. The credit card company notifies PayPal about the reason for the
chargeback. After investigating the case, PayPal notifies the merchant of any action
required.
NOTE: The IPN messages for chargebacks resulting from a complaint are asynchronous:
the IPN message for the chargeback can be sent to the merchant before the IPN
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.
46 October 2006 Order Management Integration Guide
Transaction History and Reporting Tools
Dispute Report
IPN variables for cases include the type of case, the reason, and other information about the
case. For details about all variables and their possible values, see “Dispute Notification
Variables” on page 68.
With the dispute report, you can focus only on transactions that are disputed by customers for
some reason.
FIGURE 4.5 Dispute Report
Programmatic Access to Dispute Report
The Downloadable Dispute Report (DDR) provides merchants with a regular report of newly
created disputes and changes in the status of those cases that are already open and are in the
midst of processing.
The report is designed for the merchant that processes large volumes of payments. Thus, while
the report resembles the Dispute Report available via the Resolution Center within the PayPal
site, the DDR differs in that it contains all open records and the invoice ID which can be used
to track dispute cases based on your transactional identifiers. The DDR cannot filter on open
records.
NOTE: To use this feature, you must sign up for the report through your PayPal Account
Manager.
Order Management Integration Guide October 2006 47
Transaction History and Reporting Tools
Dispute Report
Content of the Report
The report contains information about all chargebacks and buyer complaints generated for
your account. This report does not contain information about ACH returns of PayPal
unauthorized complaints.
First DDR Report
When you first sign up for the DDR, the report contains:
z All open chargebacks, regardless of the date the case was created or the current status of
the case
z 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:
z New cases created
z Cases that were modified, including cases that were closed
Frequency / Archiving
The DDR is generated every day based on activity for the previous day. Days with no activity
will generate an empty report.
PayPal will maintain DDR reports for seven days after which the report will not longer be
available.
Report Set Up
To use the DDR you must:
1. Sign up for the report through your PayPal Account Manager
2. Create a unique user to download the report
3. Write code to download the report from a PayPal server
Step 1. Sign up for the report via PayPal Account Management. Contact your PayPal
Account Manager to sign up for the Downloadable Dispute Report.
Step 2. Create a Unique User on PayPal to Download the Report. T o 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.
48 October 2006 Order Management Integration Guide
Transaction History and Reporting Tools
Dispute Report
3. Click the Multi-User Access link under the Account Information column to open the
Multi-User Access page.
4. Click the Add button. On the Multi-User Access page, enter the requested information
into the fields provided.
5. Select the checkboxes next to each of the choices that you want the alias to have.
6. Click Save.
Your new user and alias appear on the Multi-User Access page along with a confirmation
message that you have successfully added a new user to your account.
Step 3. Write Code to Download the Report from the PayPal Server. W rite code to
request the report from a PayPal server. The code must send an HTTP POST to the PayPal
server. The POST must be sent from a secure server that uses HTTPS. PayPal does not accept
requests from servers using HTTP.
You can automate which details you want to be prioritized in your Settlement File reports by
assigning values as depicted in the sample HTML code.
The HTML code below is an example of the values that your DDR may contain. In the
following example, the uname value is the alias created using the Multi-User Access feature.
<FORM ACTION=”https://www.payp al.com/us/DISPUTE- REPORT-SCHED-LOGIN”
METHOD=”post”>
<INPUT TYPE=”hidden” NAME=”day ” VALUE=”16”>
<INPUT TYPE=”hidden” NAME=”mon th” VALUE=”09”>
<INPUT TYPE=”hidden” NAME=”year” VALUE =”2006”>
<INPUT TYPE=”hidden” NAME=”una me” VALUE=”queuealias2”>
<INPUT TYPE=”hidden” NAME=”pwo rd” VALUE=”22222222”>
<INPUT TYPE=”image” VALUE=”Submit”>
</FORM>
View the Report
You will receive an email when the report is ready. This email contains a link to the report
which can you access via a browser.
You can also use the email as a trigger for your code to programmatically access the report.
Order Management Integration Guide October 2006 49
Transaction History and Reporting Tools
Dispute Report
50 October 2006 Order Management Integration Guide
IPN and PDT Variables
A
IPN and PDT variables are case-sensitive. All values are lowercase, except those for
payment_status, which have an initial capital letter.
In addition, values posted by IPN are URL-encoded. For example, a colon in http:// is
encoded as %3A in the IPN post: http%3A//
About These Tables of Variables
The tables in this appendix group IPN variables by different characteristics:
z “test_ipn Variable in Sandbox” on page 51
z “IPN Variables in All Posts” on page 52
z “Buyer Information” on page 52
z “Basic Information” on page 53
z “Advanced and Custom Information” on page 54
z “Website Payments Standard and Refund Information” on page 55
z “Currency and Currency Exchange” on page 60
z “Auctions” on page 61
z “Mass Payment” on page 62
z “Dispute Notification Variables” on page 68
z “PDT-Specific Variables” on page 69
Transaction-Specifc Variable Values
Unless otherwise indicated in the table column labeled Possible Values, the value of an IPN or
PDT variable is always specific to the transaction whose information is being posted.
test_ipn Variable in Sandbox
In the Sandbox environment, IPN includes the additional variable test_ipn with a value of 1
(one). The purpose of test_ipn is to provide testing programs a means to different i ate
between Sandbox IPN and live IPN.
Order Management Integration Guide October 2006 51
IPN and PDT Variables
IPN Variables in All Posts
IPN Variables in All Posts
IPN Version: notify_version
The value of the notify_version variable is the version number of Instant Payment
Notification that makes the post.
NOTE: The value notify_version is a means for PayPal to track versions of IPN. There is
no need for your programs to store this value or query it.
Security Information: verify_sign
The value of of verify_sign is an encrypted string used to validate the authenticity of the
transaction.
Buyer Information
TABLE A.1 IPN and PDT Variables: Buyer Information
Variable
Name
address_
city
address_
country
address_
country_
code
address_
name
address_
state
address_
status
Possible
Values Description
confirmed
unconfirmed
Character
Length
City of customer’s address. 40
Country of customer’s address. 64
Two-character ISO 3166 country code 2
Name used with address (included when the customer provides
a Gift Address)
State of customer’s address 40
Customer provided a confirmed address.
Customer provided an unconfirmed address.
128
address_
street
address_zip Zip code of customer’s address. 20
first_name Customer’s first name 64
Customer’s street address. 200
52 October 2006 Order Management Integration Guide
T
ABLE A.1 IPN and PDT Variables: Buyer Information
IPN and PDT Variables
Basic Information
Variable
Name
last_name Customer’s last name 64
payer_
business_
name
payer_email Customer’s primary email address. Use this email to provide
payer_id Unique customer ID. 13
payer_
status
residence_
country
Possible
Values Description
Customer’s company name, if customer represents a business 127
any credits.
verified
unverified
Customer has a Verified PayPal account.
Customer has an Unverified PayPal account.
Two-character ISO 3166 country code 2
Basic Information
Character
Length
127
T
ABLE A.2 IPN and PDT Variables: Basic Information
Variable
Name
business Email address or account ID of the payment recipient (that is,
item_name Item name as passed by you, the merchant. Or, if not passed by
item_number Pass-through variable for you to track purchases. It will get
quantity Quantity as entered by your customer or as passed by you, the
Possible
Values Description
the merchant). Equivalent to the values of receiver_email (if
payment is sent to primary account) and business set in the
Website Payment HTML.
NOTE: The value of this variable is normalized to lowercase
characters.
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 s o forth).
passed back to you at the completion of the payment. If omitted,
no variable will be passed back to you.
merchant. If this is a shopping cart transaction, PayPal appends
the number of the item (e.g. quantity1, quantity2).
Character
Length
127
127
127
Order Management Integration Guide October 2006 53
IPN and PDT Variables
Advanced and Custom Information
T
ABLE A.2 IPN and PDT Variables: Basic Information
Variable
Name
receiver_
email
receiver_id Unique account ID of the payment recipient (i.e., the merchant).
Possible
Values Description
Primary email address of the payment recipient (that is, the
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.
This is the same as the recipient's referral ID.
Advanced and Custom Information
T
ABLE A.3 IPN and PDT Variables: Advanced and Custom Information
Variable
Name
custom Custom value as passed by you, the merchant. These are pass-
Possible
Values Description
through variables that are never presented to your customer
Character
Length
127
13
Character
Length
255
invoice Passthrough variable you can use to identify your Invoice
Number for this purchase. If omittted, no variable is passed
back.
memo Memo as entered by your customer in PayPal Website Payments
note field.
option_
name_1
Option 1 name as requested by you.
If this is a shopping cart transaction, see
Table A.4, “IPN and
PDT Variables: Website Payments Standard and Refund
for more information.
Table A.4, “IPN and
option_
name_2
Information,” on page 55
Option 2 name as requested by you.
If this is a shopping cart transaction, see
PDT Variables: Website Payments Standard and Refund
for more information.
Table A.4, “IPN and
option_
selection1
Information,” on page 55
Option 1 choice as entered by your customer.
If this is a shopping cart transaction, see
PDT Variables: Website Payments Standard and Refund
Information,” on page 55
for more information.
127
255
64
64
200
54 October 2006 Order Management Integration Guide
IPN and PDT Variables
Website Payments Standard and Refund Information
T
ABLE A.3 IPN and PDT Variables: Advanced and Custom Information
Variable
Name
option_
selection2
Possible
Values Description
Option 2 choice as entered by your customer.
If this is a shopping cart transaction, see
Table A.4, “IPN and
PDT Variables: Website Payments Standard and Refund
Information,” on page 55
tax Amount of tax charged on payment.
If this is a shopping cart transaction, see
for more information.
Table A.4, “IPN and
PDT Variables: Website Payments Standard and Refund
Information,” on page 55
for more information.
Website Payments Standard and Refund Information
ABLE A.4 IPN and PDT Variables: Website Payments Standard and Refund
T
Information
Variable
Name
Possible
Values Description
Character
Length
200
Character
Length
auth_id Transaction-
specific
auth_exp Transaction-
specific
auth_amount Transaction-
specific
auth_status Completed
Pending
Voided
mc_gross_x Transaction-
specific for
multiple
currencies
mc_
handling_x
Transactionspecific for
multiple
currencies
Authorization identification number 19
Authorization expiration date and time, in the following format:
HH:MM:SS DD Mmm YY, YYYY PST
Authorization amount
Status of authorization
The amount is in the currency of mc_currency, where x is the
shopping cart detail item number. The sum of mc_gross_x
should total mc_gross.
The x is the shopping cart detail item number. The
handling_cart cart-wide Website Payments variable is also
included in the mc_handling variable; for this reason, the sum
of mc_handling_x might not be equal to mc_handling
28
Order Management Integration Guide October 2006 55
IPN and PDT Variables
Website Payments Standard and Refund Information
T
ABLE A.4 IPN and PDT Variables: Website Payments Standard and Refund
Information
Variable
Name
mc_
shipping_x
num_cart_
items
option_
name1
option_
name2
option_
selection1_
x
option_
selection2_
x
Possible
Values Description
Transactionspecific for
multiple
currencies
This is the combined total of shipping and shipping2
WebsitePayments variables, where x is the shopping cart detail
item number. The shipp ingx variable is only shown when the
merchant applies a shipping amount for a specific item. Because
profile shipping might apply, the sum of shipping x might not
be equal to shipping.
If this is a PayPal Shopping Cart transaction, number of items in
cart.
PayPal appends the number of the item where x represents the
number of the shopping cart detail item (e.g., option_name1,
option_name2).
PayPal appends the number of the item where x represents the
number of the shopping cart detail item (e.g., option_name2,
option_name2).
PayPal appends the number of the item (e.g.,
option_selection1, option_selection2), where x
represents the number of the shopping cart detail item.
PayPal appends the number of the item where x represents the
number of the shopping cart detail item (e.g.,
option_selection1, option_selection2).
Character
Length
64
64
200
200
parent_txn_
id
payment_
date
In the case of a refund, reversal, or canceled reversal, this
variable contains the txn_id of the original transaction, while
txn_id contains a new ID for the new transaction.
Time/Date stamp generated by PayPal, in the following format:
HH:MM:SS DD Mmm YY, YYYY PST
19
28
56 October 2006 Order Management Integration Guide
IPN and PDT Variables
Website Payments Standard and Refund Information
T
ABLE A.4 IPN and PDT Variables: Website Payments Standard and Refund
Information
Variable
Name
payment_
status
Possible
Values Description
Canceled_
Reversal
Completed
Denied
Expired
Failed
Pending
Processed
Refunded
Reversed
Voided
The status of the payment:
Canceled_Reversal: A reversal has been canceled. For
example, you won a dispute with the customer, and the funds for
the transaction that was reversed have been returned to you.
Completed: The payment has been completed, and the funds
have been added successfully to your account balance.
Denied: You denied the payment. This happen s only if the
payment was previously pending because of possible reasons
described for the PendingReason element.
Expired: This authorization has expired and cannot be
captured.
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
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.
Character
Length
for
payment_
type
echeck
instant
echeck: This payment was funded with an eCheck or EFT.
instant: This payment was funded with PayPal balance, EL V,
giropay, credit card, or Instant Transfer.
Order Management Integration Guide October 2006 57
IPN and PDT Variables
Website Payments Standard and Refund Information
T
ABLE A.4 IPN and PDT Variables: Website Payments Standard and Refund
Information
Variable
Name
pending_
reason
Possible
Values Description
address
authorization
echeck
intl
multi-
currency
unilateral
upgrade
verify
other
This variable is set only if payment_status = Pending.
address: The payment is pending because your customer did
not include a confirmed shipping address and your Payment
Receiving Preferences is set yo allow you to manually accept or
deny each of these payments. To change your preference, go to
the Preferences section of your Profile.
authorization: You set <PaymentAction>
Authorization</PaymentAction> on
SetExpressCheckoutRequest and have not yet captured
funds.
echeck: The payment is pending because it was made by
mEFT and PayPal hasn't received the funds yet or an eCheck
that has not yet cleared.
intl: The payment is pending because you hold a non-U.S.
account and do not have a withdrawal mechanism. You must
manually accept or deny this payment from your Account
Overview.
multi-currency: You do not have a balance in the currency
sent, and you do not have your 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 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.
Character
Length
58 October 2006 Order Management Integration Guide
IPN and PDT Variables
Website Payments Standard and Refund Information
T
ABLE A.4 IPN and PDT Variables: Website Payments Standard and Refund
Information
Variable
Name
reason_code chargeback
Possible
Values Description
This variable is set if payment _status =Reversed ,
guarantee
buyer_
complaint
refund
other
Refunded, or Cancelled_Reversal
chargeback: A reversal has occurred on this transaction due to
a chargeback by your customer.
guarantee: A reversal has occurred on this transaction due to
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_
settle
shipping Transaction-
Transactionspecific
specific
Remaining amount that can be captured with Authorization and
Capture
Shipping charges associated with this transaction.
Format: unsigned, no currency symbol, two decimal places.
tax PayPal appends the number of the item (e.g., item_name1,
item_name2). The tax_x variable is included only if there was
a specific tax amount applied to a particular shopping cart item.
Because profile tax may apply to other items in the cart, the sum
of tax_x might not total to tax.
Character
Length
transaction
_
entity
auth
reauth
order
Authorization and Capture trans action entity
payment
txn_id A unique transaction ID generated by PayPal. 19
txn_type cart
express_
checkout
send_money
virtual_
terminal
web-accept
cart: Transaction created by a customer:
z Via the PayPal Shopping Cart feature.
z Via Express Checkout when the cart contains mul tiple
items.
express_checkout: Transaction created by Express
Checkout when the customer’s cart contains a single item.
send-money: Transaction created by customer from the Send
Money tab on the PayPal website.
virtual_terminal: Transaction created with Virtual
Terminal.
web-accept: Transaction created by customer via Buy Now,
Donation, or Auction Smart Logos.
Order Management Integration Guide October 2006 59
IPN and PDT Variables
Currency and Currency Exchange
Currency and Currency Exchange
TABLE A.5 IPN and PDT Variables: Currency and Currency Exchange Information
Variable
Name
exchange_
rate
mc_currency Three-
mc_fee Transaction fee associated with the payment. mc_gros s minus
mc_gross Full amount of the customer's payment, before transaction fee is
mc_handling
#
Possible
Values Description
Exchange rate used if a currency conversion occurred.
For payment IPNs, this is the currency of the payment. For non-
character
currency code.
See table of
supported
currencies.
payment subscription IPNs, this is the currency of the
subscription.
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.
subtracted. Equivalent to payment_gros s for USD payments.
If this amount is negative, it signifies a refund or reversal, and
either of those payment statuses can be for the full or partial
amount of the original transaction.
Total handling amount associated with the transaction.
If this is a shopping cart transaction, see
Table A.4, “IPN and
PDT Variables: Website Payments Standard and Refund
Information,” on page 55
for more information.
Character
Length
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 and Refund
for more information.
payment_fee Transaction-
specific for
USD payments
only
Information,” on page 55
USD transaction fee associated with the payment.
payment_gross minus payment_fee equals the amount
deposited into the receiver email account. Is empty for non-USD
payments. If this amount is negative, it signifies a refund or
reversal, and either of those payment statuses can be for the full
or partial amount of the original transaction fee.
NOTE: This is a deprecated field. Use mc_fee instead.
60 October 2006 Order Management Integration Guide
IPN and PDT Variables
Auctions
T
ABLE A.5 IPN and PDT Variables: Currency and Currency Exchange Information
Variable
Name
payment_
gross
settle_
amount
settle_
currency
Auctions
Possible
Values Description
Transactionspecific for
USD payments
only
Threecharacter
currency code.
See table of
supported
currencies.
Full USD amount of the customer’s payment, before transaction
fee is subtracted. Will be empty for non-USD payments. This is
a legacy field replaced by mc_gross. 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.
Amount that is deposited into the account’s primary balance
after a currency conversion from automatic conversion (through
your Payment Receiving Preferences) or manual conversion
(through manually accepting a payment).
Currency of settle_amount.
Character
Length
T
ABLE A.6 IPN and PDT Variables: Auctions
Variable
Name
auction_
buyer_id
auction_
closing_
date
auction_
multi_item
for_auction true This is an auction payment—payments made using Pay for
Order Management Integration Guide October 2006 61
Possible
Values Description
The customer’s auction ID. 64
The auction’s close date, in the following format: HH:MM:SS
DD Mmm YY, YYYY 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.
eBay Items or Smart Logos—as well as Send Money/Money
Request payments with the type eBay items or Auction Goods
(non-eBay).
Character
Length
28
IPN and PDT Variables
Mass Payment
Mass Payment
TABLE A.7 IPN and PDT Variables: Mass Payment
Variable
Name
masspay_
txn_id_x
mc_currency_xTransaction-
mc_fee_x Transaction-
mc_gross_x Transaction-
payment_
date
Possible
Values Description
specific for
multiple
currencies
specific for
multiple
Currencies
specific for
Multiple
Currencies
For Mass Payments, a unique transaction ID generated by the
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
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
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
Character
Length
19
28
payment_fee_xTransaction-
specific for
EUR payments
only
payment_
gross_x
payment_
status
Transactionspecific for
USD payments
only
Completed
Denied
Processed
If the payment is EUR, then the value is the same as that for
mc_fee_x, where x is the record number; if the currency is not
EUR, then this is an empty string.
NOTE: This is a deprecated field. Use mc_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. Use mc_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.
62 October 2006 Order Management Integration Guide
T
ABLE A.7 IPN and PDT Variables: Mass Payment
IPN and PDT Variables
Mass Payment
Variable
Name
reason_code 1001
Possible
Values Description
This variable is only set if st atus = Failed.
1003
1004
1001: Invalid UserID.
1003: Country of Residence check failure
1004: Country of Funding Source check failure
receiver_
email_x
status_x Completed
Failed
Reversed
Unclaimed
For Mass Payments, the primary email address of the payment
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
the funds have been returned because the Receiver’s account
was locked.
Unclaimed: This is for unilateral payments that are unclaimed.
txn_type masspay This payment was sent via Mass Payment
unique_id_x For Mass Payments, the unique ID from inp ut, where x is the
record number. This allows the merchant to cross-reference the
payment
Character
Length
127
13
Order Management Integration Guide October 2006 63
IPN and PDT Variables
Mass Payment
Subscriptions Variables
Along with other IPN variables, the following variables are included in Subscriptions IPNs.
TABLE A.8 Subscriptions Variables
Possible
Variable
txn_type subscr-
subscr_date Start date or cancellation date depending on whether transaction
subscr_
effective
Values Description
subscr_signup: subscription sign -up.
failed
subscr-
cancel
subscr-
payment
subscr-
signup
subscr-eot
subscr-
modify
subscr_cancel: subscription cancellation.
subscr_failed: subscription payment failure.
subscr_payment: subscription payment.
subscr_eot: subscription’s end-of-term.
subscr_modify: subscription modification.
is subscr_signupor subscr_canc el.
Time/Date stamp generated by PayPal , in the following format:
HH:MM:SS DD Mmm YY, YYYY PST
Date when the subscription modification will be effective (only
for txn_type = subscr_modify).
Time/Date stamp generated by PayPal , in the following format:
HH:MM:SS DD Mmm YY, YYYY PST
Character
Limit
period1 (optional) Trial subscription interval in days, weeks, months,
years (example: a 4 day interval is “period1: 4 D”).
period2 (optional) Trial subscription interval in days, weeks, months, or
years.
period3 Regular subscription interval in days, weeks, mo nt hs, or years.
amount1 Amount of payment for trial period 1 for USD payments;
otherwise blank (optional).
amount2 Amount of payment for trial period 2 for USD payments;
otherwise blank (optional).
amount3 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).
64 October 2006 Order Management Integration Guide
T
ABLE A.8 Subscriptions Variables
IPN and PDT Variables
Mass Payment
Possible
Variable
mc_amount3 Amount of payment for regular subscription period, regardless
mc_currency See table of
recurring Indicates whether regular rate recurs (1 is yes, blank is no).
reattempt Indicates whether reattempts should occur upon payment
retry_at Date PayPal will retry a failed subscription payment.
recur_times The number of payment installments that will occur at the
username (optional) Username generated by PayPal and given to
password (optional) Password generated by PayPal and given to
Values Description
of currency.
For non-payment subscriptions IPNs (i.e., txn_type= signup,
supported
currencies.
cancel, failed, eot, or modify), this is the currency of the
subscription. For payment IPNs, it is the currency of the
payment (i.e., txn_type = subscr _payment)
failures (1 is yes, blank is no).
regular rate.
subscriber to access the subscription.
subscriber to access the subscription (password will be
encrypted).
Character
Limit
64
24
subscr_id ID generated by PayPal for the subscriber. 19
Variables for Each Subscription Event
The following table shows which variables are associated and can be included in IPN posts
with each subscription event type.
About payment_status and txn_type with Subscription IPN. In IPN messages posted by
Subscription events, the payment_status variable is sent when a payment or refund occurs.
For all other events, the pertinent variable is txn_type.
T
ABLE A.9 IPN Variables with Each Subscription Event
Payment
Payment
Variable Signup Cancel Modify
Basic Information
business X XXX X XX
receiver_email X XXX X XX
receiver_id XX
item_name X XXX X XX
(USD)
(MultiCurrency) Refund Failed EOT
Order Management Integration Guide October 2006 65
IPN and PDT Variables
Mass Payment
T
ABLE A.9 IPN Variables with Each Subscription Event
Payment
Payment
Variable Signup Cancel Modify
item_number X XXX X XX
Advanced and Custom Information
invoice X XXX X XX
custom X XXX X XX
option_name1 X XXX X XX
(USD)
(MultiCurrency) Refund Failed EOT
option_selecti
on1
option_name2 X XXX X XX
option_selecti
on2
Transaction Information
payment_status XX X
pending_reason XX
reason_code XX
payment_date XX
txn_id XX
parent_txn_id XX
txn_type subscr_
Currency and Exchange information
mc_gross XX
X XXX X XX
X XXX X XX
signup
subscr_
cancel
subscr_
modify
subscr_payment subscr_
failed
subscr
_
eot
mc_fee XX
mc_currency X XXX X XX
settle_amount XX
exchange_rate XX
payment_gross XXX
payment_fee X
Buyer Information
first_name X XXX X XX
66 October 2006 Order Management Integration Guide
IPN and PDT Variables
Mass Payment
T
ABLE A.9 IPN Variables with Each Subscription Event
Payment
Payment
Variable Signup Cancel Modify
(USD)
last_name X XXX X XX
(MultiCurrency) Refund Failed EOT
payer_business
X XXX X X
_name
address_name X XXX X X
address_street X XXX X X
address_city X XXX X X
address_state X XXX X X
address_zip X XXX X X
address_
X XXX X X
country
payer_email X XXX X XX
payer_id X XXX X XX
payer_status X XXX X XX
payment_type XX
Subscription Information
subscr_date XXX
subscr_
X
effective
period1 XXX
period2 XXX
period3 XXX
amount1 XXX
amount2 XXX
amount3 XXX
mc_amount1 XXX
mc_amount2 XXX
recurring XXX
reattempt XXX
retry_at X
Order Management Integration Guide October 2006 67
IPN and PDT Variables
Dispute Notification Variables
T
ABLE A.9 IPN Variables with Each Subscription Event
Payment
Variable Signup Cancel Modify
Payment
(USD)
(MultiCurrency) Refund Failed EOT
recur_times XXX
username X XXX X XX
password X XXX X XX
subscr_id X XXX X XX
Dispute Notification Variables
T
ABLE A.10 Dispute Notification Variables
Possible
Variable
Values Description
txn_type new_case A new case has been registered.
txn_type adjustment A case has been resolved and closed.
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
chargeback
z complaint: A bu yer has logged a complaint through the
PayPal Resolution Center.
z chargeback: A buyer has filed a chargeback with his credit
card company, which has notified PayPal of the reason for
the chargeback.
case_
creation_
Transactionspecific
Date and time case was registered, in the following format:
HH:MM:SS DD Mmm YY, YYYY PST
date
reason_code Depends on
Reason for the case.
value of
case_type
reason_code Values for case_type complaint
non_receipt Buyer claims that he did not receive goods or service.
68 October 2006 Order Management Integration Guide
T
ABLE A.10 Dispute Notification Variables
Possible
Variable
Values Description
IPN and PDT Variables
PDT-Specific Variables
not_as_
described
reason_code Values for case_type chargeback
unauthorized
adjustment_
reimburse
non_receipt Buyer claims that he did not receive goods or service.
duplicate Buyer claims that a possible duplic ate payment was made to the
merchandise Buyer claims that the received merchandise is unsatisfactory,
special Some other reason. Usually, special indicates a credit card
Buyer claims that the goods or service received differ from
merchant’s description of the goods or service.
A case that has been resolved and close requires a
reimbursement.
merchant.
defective, or damaged.
processing error for which the merchant is not responsible and
for which no debit to the merchant will result. PayPal must
review the documentation from the credit card company to
determine the nature of the dispute and possibly contact the
merchant to resolve it.
PDT-Specific Variables
The following variables apply only to PDT.
T
ABLE A.11 PDT-Specific Variables
Variable Description
amt Amount of the transaction
cc Currency code
cm Custom message
st Transaction status
tx Transaction ID/PDT token
Order Management Integration Guide October 2006 69
IPN and PDT Variables
PDT-Specific Variables
70 October 2006 Order Management Integration Guide
Downloadable History Log
B
Columns and Values
TABLE B.1 Downloadable History Log Columns and Values
Column Heading Description Format
Date Date transaction was initiated
(according to PayPal system time,
US-Pacific time zone).
Log sorted in reverse chronological
order by Date (most recent first)
Time Time transaction was initiated
(according to PayPal system time,
US-Pacific time zone).
Timezone The time zone used for recording
transactions in your PayPal account.
[M]M/[D]D/Y
YYY
HH:MM:SS
Alphanumeric;
three-character
codes
Payment
Button
Variable
Related IPN
Variable
payment_dat
e
subscr_date
Name 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.
alphanumeric;
128-character
limit
first_namel
ast_name
Order Management Integration Guide October 2006 71
Downloadable History Log Columns and Values
T
ABLE B.1 Downloadable History Log Columns and Values
Column Heading Description Format
Payment
Button
Variable
Related IPN
Variable
Type Type of transaction:
Add Funds from a Bank Account
ATM Withdrawal
ATM Withdrawal Reversal
Auction Payment Received
Auction Payment Sent
Canceled Fee
Canceled Payment
Canceled Transfer
Chargeback Settlement
Check Withdrawal from PayPal
Currency Conversion
Debit Card Cash Advance
Debit Card Purchase
Dividend From PayPal Money
Market
eCheck Received
eCheck Sent
Funds Added with a Personal Check
Guarantee Reimbursement
Payment Received
Payment Sent
PayPal
PayPal Balance Adjustment
Referral Bonus
Refund
Shopping Cart Payment Received
Shopping Cart Payment Sent
Subscription Payment Received
Subscription Payment Sent
Transfer Update to Add Funds from a
Bank Account
Update to Debit Card Credit
Update to eCheck Received
Update to Payment Received
Update to Payment Sent
continued...
alphanumeric;
39-character
limit
txn_type
72 October 2006 Order Management Integration Guide
Downloadable History Log Columns and Values
T
ABLE B.1 Downloadable History Log Columns and Values
Column Heading Description Format
T ype (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
Payment
Button
Variable
Related IPN
Variable
Status Status of transaction at time of
download:
Canceled
alphanumeric;
10-character
limit
Cleared
Completed
Denied
Expired
Failed
Pending
Refunded
Returned
Reversed
Unclaimed
Uncleared
Subject Subject of transaction as entered by
counterparty
alphanumeric;
256-character
limit
Currency Currency of transaction alphanumeric;
three character
limit
currency_
code
payment_
status
pending_
reason
mc_currency
settle_
currency
exchange_
rate
mc_gross
Order Management Integration Guide October 2006 73
Downloadable History Log Columns and Values
T
ABLE B.1 Downloadable History Log Columns and Values
Payment
Button
Column Heading Description Format
Gross Gross amount of transaction signed decimal amount payment_
Fee Fee (if applicable) for transaction sig ned decimal payment_fee
Net Net amount of transaction signed decimal
Variable
Related IPN
Variable
gross
settle_
amount
amount1
amount2
amount3
mc_fee
Note Note for transaction as entered by
counterparty
From Email
Address
To Email Address Email address of transaction recipient alphanumeric;
Transaction ID PayPal-generated unique transaction IDalphanumeric;
Payment Type Payment type used for transaction:
Counterparty Status Account status of buyer:
Email address of transaction sender alphanumeric;
eCheck
Instant
PayPal Funds
International – Unverified
International – Verified
Unverified
Verified
alphanumeric;
2000-character
limit
128-character
limit
128-character
limit
17-character
limit
alphanumeric;
27-character
limit
alphanumeric;
27-character
limit
payer_email
business receiver_
email
txn_id
payment_typ
e
payer_statu
s
Address Status Status of counterparty’s Shipping
Address.
Confirmed
Non-confirmed
alphanumeric;
14-character
limit
address_
status
74 October 2006 Order Management Integration Guide
Downloadable History Log Columns and Values
T
ABLE B.1 Downloadable History Log Columns and Values
Column Heading Description Format
Payment
Button
Variable
Related IPN
Variable
Item Title Specified by buyer in the website
field:
z Auction/Item Title
Or by seller in any of the following
button-creation fields:
z PayPal Shopping Cart Item Name
z Buy Now Item Name
z Donations Item Name
z Subscriptions Name
Item ID Specified by buyer in the website
field:
z Auction/Item Number
Or by seller in any of the following
button-creation fields:
z PayPal Shopping Cart Item
Number
z Buy Now ID Number
z Donations ID Nu mber
z Subscription Reference Number
Shipping Amount Specified by buyer in the website
field:
z eBay/Auction Shipping amount
Or by seller in any of the following
button-creation fields:
z PayPal Shopping Cart Shippi ng
amount
z Buy Now Shipping amount
alphanumeric;
128-character
limit
alphanumeric;
256-character
limit
unsigned
decimal
item_name item_name
item_number item_number
shipping
shipping2
handling
Insurance Amount Specified by buyer in the website
field:
z eBay/Auction Insurance amount
Sales Tax Sales Tax Amount specified in
seller’s button-creation process and
unsigned
decimal
unsigned
decimal
tax
Profile preferences
Option 1 Name Specified by seller in any of the
following button-creation fields:
z PayPal Shopping Cart Option 1
alphanumeric;
60-character
limit
on0 option_name
1
Name
z Buy Now Option 1 Na me
z Subscription Option 1 Name
Order Management Integration Guide October 2006 75
Downloadable History Log Columns and Values
T
ABLE B.1 Downloadable History Log Columns and Values
Column Heading Description Format
Payment
Button
Variable
Related IPN
Variable
Option 1 Value Entered by buyer in any of the
following website fields:
z PayPal Shopping Cart Option 1
Value
z Buy Now Option 1 Value
z Subscription Option 1 Value
Or specified by seller in any of the
following button-creation fields:
z PayPal Shopping Cart Value 1
Choices
z Buy Now Value 1 Choices
z Subscription Value 1 Choices
Option 2 Name Specified by seller in any of the
following button-creation fields:
z PayPal Shopping Cart Option 2
Name
z Buy Now Option 2 Na me
z Subscription Option 2 Name
Option 2 Value Entered by buyer in any of the
following website fields:
z PayPal Shopping Cart Option 2
Value
z Buy Now Option 2 Value
z Subscription Option 2 Value
Or specified by seller in any of the
following button-creation fields:
z PayPal Shopping Cart Value 2
Choices
z Buy Now Value 2 Choices
z Subscription Value 2 Choices
alphanumeri
c; 30character
limit
alphanumeric;
60-character
limit
alphanumeric;
30-character
limit
on1 option_name
2
on1 option_
selection1
os1 option_
selection2
Auction Site Name of Auction Site:
z eBay
z Yahoo! Auctions
z uBid.com
z Amazon.com Auctions
z MSN Auctions
z BidVille
z Other
Item URL URL of eBay/Auction Item
(eBay/Auction-specific)
alphanumeric;
20-character
limit
alphanumeric;
256-character
limit
76 October 2006 Order Management Integration Guide
Downloadable History Log Columns and Values
T
ABLE B.1 Downloadable History Log Columns and Values
Column Heading Description Format
Payment
Button
Variable
Related IPN
Variable
Closing Date Close date of eBay/Auction Item
(eBay/Auction-specific)
[M]M/[D]D/Y
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:
z PayPal Shopping Cart Invoice
Number
z Buy Now Invoi ce Number
z Subscription Invoice Number
Subscription
Number
PayPal-generated Subscription
Transaction ID Number
S-xxxxxxxxxxxxxxxx
alphanumeric;
19-character
limit
where x is the transaction ID.
Custom Number Specified by seller in any of the
alphanumeric custom custom
following button-creation fields:
z PayPal Shopping Cart Custom
Number
z Buy Now Custom Numb er
z Subscription Custom Numb er
subscr_id
Shipping Address
Line 1
First line of shipping address as
specified by counterparty
alphanumeric;
395-character
address_
street1
limit
Shipping Address
Line 2
Town/City Town/City of shipping address as
State/Province/Regi
on/County/Territor
y/Prefecture/Repub
Second line of shipping address as
specified by counterparty (if
applicable)
specified by counterparty
State/Province/Region/Territory/Prefe
cture/Republic of shipping address as
specified by counterparty
alphanumeric;
395-character
address_
street2
limit
alphanumeric address_cit
y
address_
state
lic
Zip/Postal Code Zip/Postal Code of shipping address
address_zip
as specified by counterparty
Country Country of shipping address as
specified by counterparty
Order Management Integration Guide October 2006 77
address_
country
Downloadable History Log Columns and Values
T
ABLE B.1 Downloadable History Log Columns and Values
Column Heading Description Format
Payment
Button
Variable
Related IPN
Variable
Balance 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
78 October 2006 Order Management Integration Guide
C
Country Codes
NOTE: This table lists country codes
defined by
Table 1: Country Codes
Country Code
AFGHANISTAN AF
ÅLAND ISLANDS AX
ALBANIA AL
ALGERIA DZ
AMERICAN SAMOA AS
ANDORRA AD
ANGOLA AO
ANGUILLA AI
ANTARCTICA AQ
ANTIGUA AND BAR-
BUDA
ARGENTINA AR
ARMENIA AM
ARUBA AW
AUSTRALIA AU
AUSTRIA AT
AZERBAIJAN AZ
BAHAMAS BS
BAHRAIN BH
BANGLADESH BD
ISO 3166-1.
AG
Country Code
BELARUS BY
BELGIUM BE
BELIZE BZ
BENIN BJ
BERMUDA BM
BHUTAN BT
BOLIVIA BO
BOSNIA AND HERZE-
GOVINA
BOTSWANA BW
BOUVET ISLAND BV
BRAZIL BR
BRITISH INDIAN
OCEAN TERRITORY
BRUNEI DARUSSALAM BN
BULGARIA BG
BURKINA FASO BF
BURUNDI BI
CAMBODIA KH
CAMEROON CM
CANADA CA
CAPE VERDE CV
CAYMAN ISLANDS KY
BA
IO
BARBADOS BB
79
Country Codes
Country Code
CENTRAL AFRICAN
CF
REPUBLIC
CHAD TD
CHILE CL
CHINA CN
CHRISTMAS ISLAND CX
COCOS (KEELING)
CC
ISLANDS
COLOMBIA CO
COMOROS KM
CONGO CG
CONGO, THE DEMO-
CD
CRATIC REPUBLIC OF
THE
COOK ISLANDS CK
COSTA RICA CR
COTE D'IVOIRE CI
CROATIA HR
CUBA CU
CYPRUS CY
CZECH REPUBLIC CZ
DENMARK DK
DJIBOUTI DJ
DOMINICA DM
DOMINICAN REPUBLIC DO
ECUADOR EC
EGYPT EG
EL SALVADOR SV
Country Code
EQUATORIAL GUINEA GQ
ERITREA ER
ESTONIA EE
ETHIOPIA ET
FALKLAND ISLANDS
FK
(MALVINAS)
FAROE ISLANDS FO
FIJI FJ
FINLAND FI
FRANCE FR
FRENCH GUIANA GF
FRENCH POLYNESIA PF
FRENCH SOUTHERN
TF
TERRITORIES
GABON GA
GAMBIA GM
GEORGIA GE
GERMANY DE
GHANA GH
GIBRALTAR GI
GREECE GR
GREENLAND GL
GRENADA GD
GUADELOUPE GP
GUAM GU
GUATEMALA GT
GUERNSEY GG
80
Country Code
Country Code
GUINEA GN
GUINEA-BISSAU GW
GUYANA GY
HAITI HT
HEARD ISLAND AND
HM
MCDONALD ISLANDS
HOLY SEE (VATICAN
VA
CITY STATE)
HONDURAS HN
HONG KONG HK
HUNGARY HU
ICELAND IS
INDIA IN
INDONESIA ID
KOREA, REPUBLIC OF KR
KUWAIT KW
KYRGYZSTAN KG
LAO PEOPLE'S DEMO-
LA
CRATIC REPUBLIC
LATVIA LV
LEBANON LB
LESOTHO LS
LIBERIA LR
LIBYAN ARAB JAMA-
LY
HIRIYA
LIECHTENSTEIN LI
LITHUANIA LT
LUXEMBOURG LU
IRAN, ISLAMIC REPUB-
IR
LIC OF
IRAQ IQ
IRELAND IE
ISLE OF MAN IM
ISRAEL IL
ITALY IT
JAMAICA JM
JAPAN JP
JERSEY JE
JORDAN JO
KAZAKHSTAN KZ
KENYA KE
KIRIBATI KI
KOREA, DEMOCRATIC
KP
PEOPLE'S REPUBLIC OF
MACAO MO
MACEDONIA, THE
MK
FORMER YUGOSLAV
REPUBLIC OF
MADAGASCAR MG
MALAWI MW
MALAYSIA MY
MALDIVES MV
MALI ML
MALTA MT
MARSHALL ISLANDS MH
MARTINIQUE MQ
MAURITANIA MR
MAURITIUS MU
MAYOTTE YT
MEXICO MX
Country Codes
Country Code
MICRONESIA, FEDER-
FM
ATED STATES OF
MOLDOVA, REPUBLIC OFMD
MONACO MC
MONGOLIA MN
MONTSERRAT MS
MOROCCO MA
MOZAMBIQUE MZ
MYANMAR MM
NAMIBIA NA
NAURU NR
NEPAL NP
NETHERLANDS NL
NETHERLANDS ANTI-
AN
LLES
NEW CALEDONIA NC
NEW ZEALAND NZ
NICARAGUA NI
NIGER NE
NIGERIA NG
NIUE NU
NORFOLK ISLAND NF
Country Code
PALAU PW
PALESTINIAN TERRI-
PS
TORY, OCCUPIED
PANAMA PA
PAPUA NEW GUINEA PG
PARAGUAY PY
PERU PE
PHILIPPINES PH
PITCAIRN PN
POLAND PL
PORTUGAL P T
PUERTO RICO PR
QATAR QA
REUNION RE
ROMANIA RO
RUSSIAN FEDERATION RU
RWANDA RW
SAINT HELENA SH
SAINT KITTS AND
KN
NEVIS
SAINT LUCIA LC
SAINT PIERRE AND
PM
MIQUELON
82
NORTHERN MARIANA
MP
ISLANDS
NORWAY NO
OMAN OM
PAKISTAN PK
SAINT VINCENT AND
VC
THE GRENADINES
SAMOA WS
SAN MARINO SM
Country Code
Country Code
SAO TOME AND PRINC-
ST
IPE
SAUDI ARABIA SA
SENEGAL SN
SERBIA AND MON-
CS
TENEGRO
SEYCHELLES SC
SIERRA LEONE SL
SINGAPORE SG
SLOVAKIA SK
SLOVENIA SI
SOLOMON ISLANDS SB
SOMALIA SO
SOUTH AFRICA ZA
SOUTH GEORGIA AND
GS
THE SOUTH SANDWICH
ISLANDS
SPAIN ES
SRI LANKA LK
TANZANIA, UNITED
TZ
REPUBLIC OF
THAILAND TH
TIMOR-LESTE TL
TOGO TG
TOKELAU TK
TONGA TO
TRINIDAD AND
TT
TOBAGO
TUNISIA TN
TURKEY TR
TURKMENISTAN TM
TURKS AND CAICOS
TC
ISLANDS
TUVALU TV
UGANDA UG
UKRAINE UA
UNITED ARAB EMIR-
AE
ATES
SUDAN SD
SURINAME SR
SVALBARD AND JAN
SJ
MAYEN
SWAZILAND SZ
SWEDEN SE
SWITZERLAND CH
SYRIAN ARAB REPUB-
SY
LIC
TAIWAN, PROVINCE OF
TW
CHINA
TAJIKISTAN TJ
UNITED KINGDOM GB
UNITED STATES US
UNITED ST ATES MINOR
UM
OUTLYING ISLANDS
URUGUAY UY
UZBEKISTAN UZ
VANUATU VU
VENEZUELA VE
VIET NAM VN
VIRGIN ISLANDS, BRIT-
VG
ISH
Country Codes
Country Code
VIRGIN ISLANDS, U.S. VI
WALLIS AND FUTUNA WF
WESTERN SAHARA EH
YEMEN YE
ZAMBIA ZM
ZIMBABWE ZW
84
Index
A
activities 41
address 58
address_city 52
address_country 52
address_country_code 52
address_name 52
address_state 52
address_status 52
address_street 52
address_zip 52
adjustment 68
All Activity - Advanced View 41
amount1 64
amount2 64
amount3 64
amt 69
auction_buyer_id 61
auction_closing_date 61
auction_multi_item 61
AUD 17
Australian Dollar 17
auth_amount 55
auth_exp 55
auth_id 55
auth_status 55
authorization 58
case_type 68
cc 69
chargeback 68
CHF 17
cm 69
complaint 68
Completed 55, 57
currency codes 17
custom 54
Czech Koruna 17
CZK 17
D
Danish Krone 17
Denied 57
DKK 17
duplicate 69
E
echeck 57, 58
EUR 17
Euro 17
exchange_rate 60
Expired 57
express_checkout 59
B
Balance 41
business 53
F
Failed 57
first_name 52
for_auction 61
Forint 17
C
CAD 17
Canadian Dollar 17
Canceled-Reversal 57
cart 59
case_creation_date 68
case_id 68
Order Management Integration Guide October 2006 85
G
GBP 17
Index
H
History 39
HKD 17
Hong Kong Dollar 17
HUF 17
Hungarian Forint 17
I
iif file format 43
instant 57
intl 58
invoice 54
item_name 53
item_number 53
J
Japanese Yen 17
JPY 17
K
Koruna 17
Krona 17
Krone 17
L
last_name 53
mc_shipping_x 56
memo 54
merchandise 69
monthly account statements 39
multi-currency 58
N
Net Amount 46
New Zealand Dollar 17
new_case 68
NOK 17
non_receipt 68, 69
Norwegian Krone 17
not_as_described 69
notify_version 52
num_cart_items 56
NZD 17
O
option_name_1 54
option_name_2 54
option_name1 54, 56
option_name2 54, 56
option_selection1 54
option_selection1_x 56
option_selection2 55
option_selection2_x 56
other 58
M
P
parent_txn_id 56
masspay_txn_id_x 62
mc_amount1 64
mc_amount2 64
mc_amount3 65
mc_currency 60, 65
mc_currency_x 62
mc_fee 60, 62
mc_fee_x 62
mc_gross 60
mc_gross_x 55, 62
mc_handling 60
mc_handling_x 55
mc_shipping 60
86 October 2006 Order Management Integration Guide
password 65
payer_business_name 53
payer_email 53
payer_id 53
payer_status 53
payment_ tatus 57
payment_date 56, 62
payment_fee 60
payment_fee_x 62
payment_gross 61
payment_gross_x 62
payment_status 51, 62
payment_type 57
Index
PayPal-supported currencies 17
Pending 55, 57
pending_reason 58
period1 64
period2 64
period3 64
PLN 17
Polish Zloty 17
Pound Sterling 17
Processed 57
Q
qif file format 43
quantity 53
QuickBooks 43
Quicken 43
R
reason_code 59, 63, 68
ReasonCode 57
reattempt 65
receiver_ email_x 63
receiver_email 53, 54
receiver_id 54
recur_times 65
recurring 65
Refunded 57
remaining_settle 59
residence_country 53
retry_at 65
Reversed 57
subscr_date 64
subscr_effective 64
subscr_eot 64
subscr_failed 64
subscr_id 65
subscr_modify 64
subscr_payment 64
subscr_signup 64
Swedish Krona 17
Swiss Franc 17
T
tax 55, 59
test_ipn 51
transaction search (online) 40
transaction_entity 59
tx 69
txn_id 59, 68
txn_type 59, 63, 64, 68
U
U.S. Dollar 17
unauthorized 69
unilateral 58
unique_id_x 63
upgrade 58
URL-encoding in IPN data 51
USD 17
username 65
V
S
SEK 17
send_money 59
settle_amount 61
settle_currency 61
SGD 17
shipping 59
Singapore Dollar 17
special 69
st 69
status_x 63
subscr_cancel 64
Order Management Integration Guide October 2006 87
verify 58
verify_sign 52
virtual_terminal 59
Voided 55, 57
W
web 59
Y
Yen 17
Index
Z
Zloty 17
88 October 2006 Order Management Integration Guide
Loading...