PayPal Order Management - 2005 Integration Guide

Download

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: August 2005

PayPal Order Management Integration Guide

PayPal (Europe) Ltd. is authorised and regulated by the Financial Services Authority in the United Kingdom as an electronic money institution. PayPal FSA Register Number: 226056.

Notice of Non-Liability

PayPal, Inc. and the authors assume no liability for errors or omissions, or for damages, resulting from the use of this Manual or the information contained in this Manual.

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . .11

Email. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Differences between Instant Payment Notification (IPN) and Payment Data Transfer (PDT) 12

SSL Not Required for IPN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

PayPal-Supported Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 2 Payment Data Transfer . . . . . . . . . . . . . . . . . . .15

How PDT Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Enabling Payment Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Getting and Using the Identity Token . . . . . . . . . . . . . . . . . . . . . . . . . . 19

PDT and PayPal Account Optional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

PDT Notification Synch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Constructing the POST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

PayPal Response to POST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

PDT and Auto Return: Messaging to Buyer . . . . . . . . . . . . . . . . . . . . . . . 21

Preventing Fraud. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Chapter 3 Instant Payment Notification (IPN) . . . . . . . . . . . . .23

How It Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

How IPN POSTs Are Sent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Setting Up IPN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

IPN Notification and Notification Validation . . . . . . . . . . . . . . . . . . . . . . . . . 26

Shared Secret Per Transaction or by Profile Setting . . . . . . . . . . . . . . . . . . 26

Shared Secret Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

HTTPS Postback to PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Using IPN with Multiple Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

payment_gross and payment_fee . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Examples of Multi-currency IPN Variables. . . . . . . . . . . . . . . . . . . . . . . . 29

Order Management Integration Guide August 2005 3

Contents

Dispute Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Chapter 4 Downloadable History Log . . . . . . . . . . . . . . . . .33

Customizing Your Downloadable History Log . . . . . . . . . . . . . . . . . . . . . . . . 34

Downloading Your History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Viewing Your Downloaded Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Appendix A IPN and PDT Variables . . . . . . . . . . . . . . . . . . .39

Data Type, Maximum Field Lengths, and URL Encoding . . . . . . . . . . . . . . . . 39

About These Tables of Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

test_ipn Variable in Sandbox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

IPN Variables in All Posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Buyer Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Basic Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Advanced and Custom Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Shopping Cart Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Currency and Currency Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Auctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Mass Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Subscriptions Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Dispute Notification Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

PDT-Specific Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Appendix B Downloadable History Log

Columns and Values 59

Appendix C Country Codes . . . . . . . . . . . . . . . . . . . . . . . 67

ISO 3166 Standard Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

4 August 2005 Order Management Integration Guide

List of Tables

Table 1.1 PayPal-Supported Currencies, Currency Codes, and Maximum Transaction

Amounts 13

Table 4.1 IPN and PDT Variables: Buyer Information . . . . . . . . . . . . . . . . 40

Table A.1 IPN and PDT Variables: Basic Information . . . . . . . . . . . . . . . . . 41

Table A.2 IPN and PDT Variables: Advanced and Custom Information. . . . . . . . 42

Table A.3 IPN and PDT Variables: Shopping Cart Information . . . . . . . . . . . . 43

Table A.4 IPN and PDT Variables: Currency and Currency Exchange Information. . 46

Table A.5 IPN and PDT Variables: Auctions . . . . . . . . . . . . . . . . . . . . . 47

Table A.6 IPN and PDT Variables: Mass Pay . . . . . . . . . . . . . . . . . . . . . 48

Table A.7 Subscriptions Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Table A.8 IPN Variables with Each Subscription Event . . . . . . . . . . . . . . . . 52

Table A.9 Dispute Notification Variables . . . . . . . . . . . . . . . . . . . . . . . 54

Table A.10 PDT-Specific Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Table B.1 Downloadable History Log Columns and Values . . . . . . . . . . . . . . 59

Table C.1 ISO 3166 Two-Character Country Codes. . . . . . . . . . . . . . . . . . 67

Order Management Integration Guide August 2005 5

List of Tables

6 August 2005 Order Management Integration Guide

List of Figures

Figure 4.1 The Download My History Link . . . . . . . . . . . . . . . . 34

Figure 4.2 Customize My History Download . . . . . . . . . . . . . . . 35

Figure 4.3 Download History Page . . . . . . . . . . . . . . . . . . . 36

Figure 4.4 A Comma-Separated Value History log in a spreadsheet file. . 38

Figure 4.5 A comma-delimited history log in a text file . . . . . . . . . 38

Order Management Integration Guide August 2005 7

List of Figures

8 August 2005 Order Management Integration Guide

Preface

This Document

This release of the PayPal Order Management Integration Guide, a document that describes the PayPal features for managing orders, such as Payment Data Transfer (PDT), Instant Payment Notification (IPN), and Downloadbale History Log, replaces the version released in June, 2005.

This document replaces portions of the Merchant User Manual and Integration Guide issued in April, 2005.

Intended Audience

This document is written for merchants who use PayPal to manage order information.

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, “Downloadable History Log,” describes the Downloadable History Log and how

you can use it to reconcile payment transactions.

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.

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.

Order Management Integration Guide August 2005 9

Preface

Typeface How Used

monospaced

Serif bold User interface names, such as window names or menu selections.

San-serif oblique

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.

For example: On the Profile page, click Email to confirm your email address. Placeholders used in the context of a format or programming standard or formal

descriptions of PayPal system syntax. Placeholders indicate values or names that the reader should provide.

Example: For example, amount is the variable for a single-item shopping cart, but

amount_

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

Documentation Problems

Hypertext link to a page in the current document or to another document in the set. Hypertext link to a URL or that initiates a web action, such as sending mail.

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:

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.

10 August 2005 Order Management Integration Guide

Email

Introduction

PayPal offers four payment notification methods for backend integration:

z Email z Reporting To ols 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 n eed 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:

z Monthly Account Statements: View a summary of all credits and debits that have

z Merchant Sales Reports: Every week, receive valuable analysis of revenue by sales

Payments and Instant Purchase checkbox.

affected your account balance each month.

channel and currency.

z History Log: View an online record of your received and sent payments.

Order Management Integration Guide August 2005 11

Introduction

Differences between Instant Payment Notification (IPN) and Payment Data Transfer (PDT)

z Downloadable Logs: Keep track of your transaction history by downloading it into

various file formats (suitable for financial settlements).

For more information about PayPal's reports, see

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 eCheck clearings, reversals, and refunds.

SSL Not Required for IPN

Because credit card and bank information is not transmitted in Instant Payment Notification (IPN), PayPal does not require Secure Sockets Layer (SSL) to encrypt IPN transmissions.

12 August 2005 Order Management Integration Guide

PayPal-Supported Currencies

The following currencies are supported by PayPal.

TABLE 1.1 PayPal-Supported Currencies, Curre ncy Codes, an d Maximum

Transaction Amounts

Code Currency

AUD Australian Dollar 12,500 AUD CAD Canadian Dollar 12,500 CAD EUR Euro 8,000 EUR GBP Poun d Sterling 5,500 GBP JPY Japanese Yen 1,000,000 JPY USD U.S. Dollar 10,000 USD

Introduction

PayPal-Supported Currencies

Maximum Transaction Amount

Order Management Integration Guide August 2005 13

Introduction

PayPal-Supported Currencies

14 August 2005 Order Management Integration Guide

Payment Data Transfer

Payment Data Transfer (PDT) provides merchants with the ability to display transaction details to buyers who are redirected back to their site upon payment completion.

NOTE: You must enable Auto Return for Website Payments to use Payment Data Transfer.

Auto Return brings your buyers back to your website immediately after payment completion. Auto Return applies to PayPal Website Payments, including Buy Now, Donations, Subscriptions, and Shopping Cart. For more information about Auto Return, see the PayPal Website Payments Standard Integration Guide.

How PDT Works

Bob is going to purchase a widget from the Widget Warehouse.

Step 1: Bob goes to the Widget Warehouse website, finds the widget he wants, and clicks Buy Now.

Order Management Integration Guide August 2005 15

Payment Data Transfer

How PDT Works

Step 2: Bob is taken to a PayPal Payment Details page which displays the details of the payment he is about to make.

Step 3: Bob enters his PayPal account information into the PayPal Login fields. Step 4: Bob is then taken to a confirmation page that displays the details of his selection,

information about how his automatic payments will be funded, and his shipping information. He clicks Pay to complete the payment.

16 August 2005 Order Management Integration Guide

Payment Data Transfer

How PDT Works

Step 5: A payment confirmation page appears that informs Bob that his payment has been completed and that he is being redirected back to the Widget Warehouse website.

Step 6: A transaction token is passed to the return URL provided by the Widget Warehouse. The Widget Warehouse fetches the transaction token and retrieves the transaction details from PayPal via an HTTP POST. 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 19. For more information about the HTTP POST, see “PDT Notification Synch” on page 20.

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.

For example, as shown in the following diagram: Thank you for your payment. Your transaction has been completed, and a receipt for your purchase has been emailed to you. You may log into your account at

www.paypal.com to view details of this transaction.

Order Management Integration Guide August 2005 17

Payment Data Transfer

Enabling Payment Data Transfer

Step 8: Bob receives an email receipt for this transaction, confirming his purchase and including a copy of the payment details, the Widget Warehouse's business information, and his confirmed shipping address.

Enabling Payment Data Transfer

To enable PDT:

1. Click the My Account tab.

2. Click the Profile subtab.

3. Click the Website Payment Preferences link, as shown in the following diagram.

The Website Payment Preferences page opens.

18 August 2005 Order Management Integration Guide

4. Click the Payment Data Transfer On radio button, as shown in the following diagram.

NOTE: 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.

Payment Data Transfer

PDT and PayPal Account Optional

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 and PayPal Account Optional

The PayPal Account Optional does not require your customers who are new to PayPal to create a PayPal account to complete a purchase—they go through an alternate checkout and have the option to sign up afterward. Customers who already have PayPal accounts will continue to enjoy the privileges of those accounts, such as payment history and integration with eBay Auctions, and their checkout experience will remain the same.

This PayPal Account Optional feature is available for Buy Now, Donations, and Shopping Cart buttons, but not for Subscription buttons.

Order Management Integration Guide August 2005 19

Payment Data Transfer

PDT Notification Synch

PayPal Account Optional is enabled by default. If the merchant has turned on Payment Data Transfer and has not disabled PayPal Account Optional, a new user will not be automatically directed back to the merchant website, but will be given the option to return. When the buyer clicks Continue, the transaction ID associated with the transaction is sent. The merchant returns the transaction ID, along with their identity token, and PayPal then sends the merchant payment information that confirms that the payment is complete. The buyer is directed back to the merchant site where the transaction information is displayed. However, if the buyer does not click Continue, they will not be directed back to the merchant's site and PDT will not be initiated.

PDT Notification Synch

After you have activated PDT, every time a buyer makes a website payment and is redirected to your return URL, a transaction token is sent 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=

4. You must post your identity token using the variable at and the value of your PDT identity

token:

at=

your_identity_token

For information about the identity token, see “Getting and Using the Identity Token” on

page 19.

https://www.paypal.com/cgi-bin/webscr.

20 August 2005 Order Management Integration Guide

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 both be URL-encoded strings. This response data needs to be parsed appropriatel y 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 ...

If the response is FAIL, PayPal recommends making sure that:

Payment Data Transfer

PDT Notification Synch

key=value where key and value are

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 echecks that do not immediately clear.

For a list of PDT variables, see Appendix A, “IPN and PDT Variables.”

Order Management Integration Guide August 2005 21

Payment Data Transfer

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.

z ASP/VBScript z ColdFusion z PERL z PHP

22 August 2005 Order Management Integration Guide

Instant Payment Notification

(IPN)

Instant Payment Notification (IPN) allows you to integrate PayPal payments with your website’s back-end operations. IPN provides immediate notification and confirmation of PayPal payments you receive, allowing you to:

z Customize your website’s response to customer purchases in real-time. z Track customers through the notification’s “pass through” variables. z Automate your fulfillment operations. z Store transaction information in your own database.

To activate Instant Payment Notification, you will need to go to your Profile to enter the URL at which you would like to receive notification posts. Once you activate IPN, you will receive an IPN when a payment is first sent which will state the status of the payment (Completed or Pending). If the payment was “Pending,” you will receive another IPN when the payment clears, fails, or is denied.

IPN can be seamlessly integrated with each of the PayPal Website Payments solutions — Buy Now Buttons, PayPal Shopping Cart, Subscriptions and Recurring Payments, and Donation s — and with regular PayPal Send Money and Mass Pay payments. It lets you focus on selling, not on manually tracking your orders.

How It Works

When a customer makes a payment to you or a payment is reversed or refunded, PayPal will post a notification to your server at the URL you specified. Included in this notification will be all of your customer’s payment information (e.g. customer name, payment amount) as well as a piece of encrypted code. When your server receives a notification, it will then post the information, including the encrypted code, back to a secure PayPal URL. PayPal will authenticate the transaction and send confirmation of its validity back to your server.

After you have activated Instant Payment Notification, your server will be sent a notification every time you receive a payment. This notification will be sent as a hidden “FORM POST” to the URL you specified, and will include all of the payment information. The FORM variables for these notifications are available in Appendix A of this manual.

Order Management Integration Guide August 2005 23

Instant Payment Notification (IPN)

How IPN POSTs Are Sent

Step 1: Your buyer comes to your website and clicks on a PayPal Buy Now button to make a purchase.

Step 2: After your buyer checks the payment details and sends the payment, he will see a confirmation page, as shown in the following diagram.

Step 3: At the time the payment is made, PayPal will post a notification to your server at the URL you specified. All of your customer’s payment information and a piece of encrypted code will be included in this notification.

Step 4: On receiving the notification, your server validates the notification for the security of your customer and your payment. There are two ways to validate the notification. For details, see “IPN Notification and Notification Validation ” on page 26.

24 August 2005 Order Management Integration Guide

Step 5: After verifying the correctness of the data from IPN, you can update your database with the IPN data and process the purchase.

Setting Up IPN

To set up IPN:

1. Log in to your Business or Premier PayPal account.

Instant Payment Notification (IPN)

Setting Up IPN

2. Click the Profile subtab.

3. Click the Instant Payment Notification Preferences link in the Selling Preferences

column.

4. Click Edit.

5. Click the checkbox and enter the URL at which you would like to receive your IPN

Notifications.

6. Click Save. Alternatively, you can activate IPN by including the notify_url field in your PayPal

button. This field specifies the URL of a script that can process the IPN. For a complete list of IPN fields, variables, and sample code, see Appendix A, “IPN and PDT

Variables.” Code samples for the following development environments are also available on

the PayPal website at

z ASP.Net/C# z ASP/VBScript z ColdFusion z Java/JSP z PERL

http://www.paypal.com/cgi-bin/webscr?cmd=p/xcl/rec/ipn-code-out side:

z PHP

Order Management Integration Guide August 2005 25

Instant Payment Notification (IPN)

IPN Notification and Notification Validation

After your server receives Instant Payment Notification, you must confirm that you received it. This is known as notification validation, which is a means for PayPal to help you prevent spoofing or “man-in-the-middle” attacks.

You have two methods by which you can validate the notification:

1. Sending a shared secret, described in “Shared Secret Validation” on page 27. PayPal

recommends this method because it 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, described in “HTTPS Postback

to PayPal” on page 27. 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 yo u 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.

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.

26 August 2005 Order Management Integration Guide

Shared Secret Validation

The first and recommended method for notification validation is to use a shared secret on individual payment transactions. Add a shared secret variable and value to the value of the notify_url variable to which the IPN data is posted after a payment is made. 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://www.mysite. com/PP-IPN-Validat e.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 Standard Checkout Integration Guide.

Instant Payment Notification (IPN)

IPN Notification and Notification Validation

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.

IMPORTANT: 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.

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 d oin g so.

1. Your POST must be sent to

2. You must include the variable cmd with the value _notify-validate:

https://www.paypal.com/cgi-bin/webscr.

cmd=_notify-validate

3. You must post all the form variables you received exactly as you received them.

Order Management Integration Guide August 2005 27

Instant Payment Notification (IPN)

Using IPN with Multiple Currencies

PayPal Response to Postback

PayPal responds to the postback with a single word in the body of the response: VERIFIED or INVALID.

When you receive a VERIFIED response, perform the following checks:

1. Check that the payment_status is Completed.

2. If the payment_status is Completed, check the txn_id against the previous PayPal

transaction you have processed to ensure it is not a duplicate.

3. 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).

Using IPN with Multiple Currencies

With multiple currencies, you can accept payments in any of the PayPal-supported currencies (see Table 1.1, “PayPal-Su pported Currencies, Currency Codes, and Maximum Transaction

Amounts” on page 13). 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 U.S. Dollars, you will need to set up your buttons for your currency of choice.

payment_gross and payment_fee

These variables reflect the amount received and corresponding fee of U.S. Dollar (USD) payments. If the amount received and fee deducted are in a currency other than USD, the variables will still appear in your IPN, but will have no values in them.

http://www.paypal.com/wf/,

NOTE: payment_fee is not always present in IPNs, such as when a payment is pending.

28 August 2005 Order Management Integration Guide

These values are absent for non-USD payments so that IPN scripts will not process these amounts as USD. However, legacy IPN scripts will continue to work as before as long as the merchant only receives USD payments.

Examples of Multi-currency IPN Variables

IPNs that use the payment_gross variable will have the following multi-currency variables added. The variables mc_gross and mc_fee will not be added to IPNs with txn_type: subscr_signup, subscr_cancel, subscr_modify, su bscr_failed, or subscr_eot.

z mc_gross: Full amount of payment received, before transaction fee.

NOTE: If payment is in USD, the payment_gross value equals mc_gross.

z mc_fee: Transaction fee associated with the payment. Variable function like

payment_fee variable (variable does not appear when payment pending, and so on).

NOTE: If payment is in USD, the payment_fee value equals mc_fee.

z mc_currency: Currency of mc_gross, mc_fee, payment_gross, and payment_fee

amounts. Possible values are detailed in Table 1.1, “PayPal-Supported Currencies,

Currency Codes, and Maximum Transaction Amounts” on page 13.

Instant Payment Notification (IPN)

Using IPN with Multiple Currencies

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.

Example 1

If 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.1 Multi-currency IPN: USD Payment

payment_status = Completed payment_gross = 100 payment_fee = 3.00 mc_gross = 100 mc_fee = 3.00 mc_currency = USD

Example 2

f a user with a CAD balance receives a $100 CAD payment, the following variables will be used for the payment:

z mc_gross and mc_fee have values. z payment_gross and payment_fee are blank.

EXAMPLE 3.2 Multi-currency IPN: CAD Payment

payment_status = Completed

Order Management Integration Guide August 2005 29

Instant Payment Notification (IPN)

Using IPN with Multiple Currencies

payment_gross = payment_fee = mc_gross =100 mc_fee = 3.00 mc_currency = CAD

Example 3

If the account is set to automatically convert payments, these variables will be used to show the conversion. This example is for a user with a USD balance who receives a payment of 100 GBP:

EXAMPLE 3.3 Mu tli-currenc y IPN: Automa tic Conversio n of GBP Payment

payment_status = Completed payment_gross = payment_fee = mc_gross = 100 mc_fee = 3.00 mc_currency = GBP settle_amount = 145.5 settle_currency = USD exchange_rate = 1.5

Example 4

If a payment received is pending due to pending_reason = multi_currency, the first IPN received would not have the settle_amount, settle_curre ncy, or exchange_rate.

EXAMPLE 3.4 Mutli-currency IPN: Pending Payment

payment_status = Pending pending_reason = multi_currency payment_gross = mc_gross = 100 mc_currency = GBP

The second IPN contains information about settling the payment. If the payment is accepted into the account’s primary currency, which is USD in the following example:

EXAMPLE 3.5 Pend ing - Con vert to Primary Currenc y

payment_status = Completed payment_gross = payment_fee = mc_gross = 100 mc_fee = 3.00 mc_currency = GBP settle_amount = 145.5 settle_currency = USD exchange_rate = 1.5

If the payment is accepted into a balance of the same currency:

30 August 2005 Order Management Integration Guide

Instant Payment Notification (IPN)

Using IPN with Multiple Currencies

EXAMPLE 3.6 Pend ing - Acce pt to Curren cy Balanc e

payment_status = Completed payment_gross = payment_fee = mc_gross = 100 mc_fee = 3.00 mc_currency = GBP

If the payment is denied:

EXAMPLE 3.7 Pend ing - Denie d

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 August 2005 31

Instant Payment Notification (IPN)

Dispute Notification

Buyers can register claims about payments; such claims are called cases. PayPal notifies merchants about new cases with email and with IPN.

There are two kinds of cases:

z Complaint: A buyer has used the PayPal Resolution Center to register a claim about a

payment to a merchant.

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.

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 54.

32 August 2005 Order Management Integration Guide

Downloadable History Log

PayPal’s Downloadable History Log makes it easier and more efficient to track, sort and print transactions from your PayPal account.

Download your transaction history into one of several available file formats outlined in this document so that you can view and store your transaction history offline.

Once you’ve downloaded your history log, you can analyze the data to learn more about your business and customer needs, as well as generate customer lists, financial statements and customized reports.

This manual is designed to provide you a comprehensive overview of the information and instructions you need to get the most from PayPal’s Downloadable History Log feature.

Order Management Integration Guide August 2005 33

Downloadable History Log

Customizing Your Downloadable History Log

Business or Premier PayPal account holders can customize their Downloadable History Log at any time.

z Add info to, or remove from, your Downloadable History Log z Modify how information is displayed in your account

For example, you can display a buyer's shipping address in a single column rather than multiple columns. Here’s how:

1. Log in to your PayPal account.

2. Click the History subtab under the My Account tab.

3. Click the Download My History link in the Reporting Tools box.

FIGURE 4.1 The Download My History Link

4. Click the Customize My History Download link.

34 August 2005 Order Management Integration Guide

Customizing Your Downloadable History Log

FIGURE 4.2 Customize My History Download

Downloadable History Log

5. A list of items appears. This is where you can select your preferences to customize your

Downloadable History Log.

6. After modifying your selections, click Save.

Order Management Integration Guide August 2005 35

Downloadable History Log

Downloading Your History

Follow the instructions below to download your transaction history.

1. Log in to your PayPal account.

2. Click the History subtab under the My Account tab.

3. Click the Download My History link in the Reporting Tools box.

FIGURE 4.3 Download History Page

4. On the next page, specify the date range. (You can check one of the boxes below to ignore

previously downloaded transactions and transactions older than 30 days).

5. Choose the desired file format.

6. Select whichever of the two checkboxes that apply.

7. Click the Download History button and save the file to a memorable location for easy

reference later.

36 August 2005 Order Management Integration Guide

Viewing Your Downloaded Log

As detailed in the previous section, your Downloadable History Log can be saved and viewed in any of the following file formats:

z Comma-separated value (CSV) plain text file for use with spreadsheet programs z Tab-delimited plain text file z Intuit (Quicken/QuickBooks) file

For automated file processing and reconciliation applications, PayPal recommends you use comma-delimited or tab-delimited formats. Comma-delimited and tab-delimited files may contain fields with punctuation and spaces.

Those fields will be automatically double-quoted (") in the file output. When viewing comma-delimited or tab-delimited file formats in spreadsheet applications (like

Excel), the log files display field column headers across the first row, and data values for individual transactions in subsequent rows. Each row is separated by a carriage return.

Downloadable History Log

Viewing Your Downloaded Log

Order Management Integration Guide August 2005 37

Downloadable History Log

Viewing Your Downloaded Log

FIGURE 4.4 A Comma-Separated Value History log in a spreadsheet file.

IGURE 4.5 A comma-delimited history log in a text file

Once the file is formatted, import the file into whatever program you use for reconciliation purposes.

38 August 2005 Order Management Integration Guide

IPN and PDT Variables

IPN and PDT variables are case-sensitive. All values are lowercase, except those for payment_status, which have an initial capital letter.

Data Type, Maximum Field Lengths, and URL Encoding

IPN posts contain only alphanumeric characters. The maximum field length for each returned field is 127 characters, with the following

exceptions:

z custom has a maximum length of 255 characters. z memo has a maximum length of 255 characters. z The unique Pa yPal Transaction ID (txn_id variable) is 17 characters long.

Values posted by IPN are URL-encoded. For example, the colon “:” in "http://" is encoded as %3A in the IPN post.

About These Tables of Variables

The tables in this appendix group IPN variables by different characteristics:

z “test_ipn Variable in Sandbox” on page 40 z “IPN Variables in All Posts” on page 40 z “Buyer Information” on page 40 z “Advanced and Custom Information” on page 42 z “Shopping Cart Information” on page 43 z “Currency and Currency Exchange” on page 46 z “Auctions” on page 47 z “Mass Payment” on page 48 z “Dispute Notification Variables” on page 54 z “PDT-Specific Variables” on page 56

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.

August 2005 39

IPN and PDT Variables

test_ipn Variable in Sandbox

In the Sandbox environment, IPN includes the additional variable test_ipn with a value of

1 (one). The purpose of test_ipn is to provide testing programs a means to

differentiate between Sanbox IPN and live IPN.

IPN Variables in All Posts

IPN Version: notify_version

The value of the notify_version variable is the version number of Instant Payment Notification that makes the post.

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 4.1 IPN and PDT Variables: Buyer Information

Variable Name Possible Values Description

address_ city

address_ country

address_ country_ code

address_ name

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)

Character Length

128

address_ state

address_ status

confirmed unconfirmed

State of customer’s address 40

Customer provided a confirmed address. Customer provided an unconfirmed address.

40 August 2005

ABLE 4.1 IPN and PDT Variables: Buyer Information

IPN and PDT Variables

Basic Information

Variable Name Possible Values Description

address_

Customer’s street address. 200

Character Length

street address_zip Zip code of customer’s address. 20 first_name Customer’s first name 64 last_name Customer’s last name 64 payer_

Customer’s company name, if customer represents a business 127

business_ name

payer_email Customer’s primary email address. Use this email to provide any

127

credits.

payer_id Unique customer ID. 13 payer_

status

residence_

verified unverified

Customer has a Verified PayPal account. Customer has an Unverified PayPal account.

Two-character ISO 3166 country code 2

country

Basic Information

ABLE A.1 IPN and PDT Variables: Basic Information

Variable Name Possible Values Description

business Email address or account ID of the payment recipient (i.e., the

merchant). Equivalent to receiver_email if payment is sent to primary account, and essentially an echo of the business variable passed in the Website Payment button HTML code.

item_name Item name as passed by you, the merchant. Or, if not passed by

you, as entered by your customer. If this is a shopping cart transaction, PayPal will append the number of the item (e.g.,

item_name1, item_name2).

item_number Pass-through variable for you to track purchases. It will get

passed back to you at the completion of the payment. If omitted, no variable will be passed back to you.

Character Length

127

August 2005 41

IPN and PDT Variables

Advanced and Custom Information

ABLE A.1 IPN and PDT Variables: Basic Information

Variable Name Possible Values Description

quantity Quantity as entered by your customer or as passed by you, the

merchant. If this is a shopping cart transaction, PayPal appends the number of the item (e.g. quantity1, quantity2).

receiver_ email

Primary email address of the payment recipient (i.e., the merchant). If the payment is sent to a non-primary email address on your PayPal account, the receiver_email will still be your primary email.

receiver_id Unique account ID of the payment recipient (i.e., the merchant).

This is the same as the recipient's referral ID.

Advanced and Custom Information

ABLE A.2 IPN and PDT Variables: Advanced and Custom Information

Variable Name Possible Values Description

Character Length

127

Character Length

custom Custom value as passed by you, the merchant. These are pass-

through variables that are never presented to your customer

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_ name1

Option 1 name as requested by you. If this is a shopping cart transaction, see

Table A.3, “IPN and

PDT Variables: Shopping Cart Information” on page 43

for

more information.

option_name 2

Option 2 name as requested by you. If this is a shopping cart transaction, see

Table A.3, “IPN and

PDT Variables: Shopping Cart Information” on page 43

for

more information.

option_ selection1

Option 1 choice as entered by your customer. If this is a shopping cart transaction, see

Table A.3, “IPN and

PDT Variables: Shopping Cart Information” on page 43

for

more information.

255

127

255

200

42 August 2005

ABLE A.2 IPN and PDT Variables: Advanced and Custom Information

IPN and PDT Variables

Shopping Cart Information

Variable Name Possible Values Description

option_ selection2

Option 2 choice as entered by your customer. If this is a shopping cart transaction, see

PDT Variables: Shopping Cart Information” on page 43

more information.

tax Amount of tax charged on payment.

If this is a shopping cart transaction, see

PDT Variables: Shopping Cart Information” on page 43

more information.

Shopping Cart Information

ABLE A.3 IPN and PDT Variables: Shopping Cart Information

Variable Name Possible Values Description

auth_id Authorization identification number auth_exp Authorization expiration date and time

Character Length

Table A.3, “IPN and

for

Table A.3, “IPN and

for

auth_amount Authorization amount auth_status Status of authorization remaining_

Remaining amount that can be captured

settle mc_gross_

x Transaction-

specific for

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. multiple currencies

mc_ handling_

Transactionspecific for multiple

The

x is the shopping cart detail item number. The handling_c art cart-wide

Website Payments variable is also included in the mc_handling variable; for

this reason, the sum of mc_handling_ currencies

mc_ shipping_

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 shippingx

variable is only shown when the merchant applies a shipping amount for a

specific item. Because profile shipping might apply, the sum of shipping

might not be equal to shipping.

num_cart_

If this is a PayPal Shopping Cart transaction, number of items in cart.

items

x might not be equal to mc_handling

August 2005 43

IPN and PDT Variables

Shopping Cart Information

ABLE A.3 IPN and PDT Variables: Shopping Cart Information

Variable Name Possible Values Description

option_ name1

option_ name2

option_ selection1_

option_ selection2_

parent_txn_ id

payment_ date

payment_ status

Canceled-

Reversal Completed Denied Expired Failed In-Progress Partially-

Refunded Pending Processed Refunded Reversed Voided

PayPal appends the number of the item where x represents the number of the shopping cart detail item (e.g.,

PayPal appends the number of the item where shopping cart detail item (e.g.,

PayPal appends the number of the item (e.g., option_selection1,

option_name1, option_name2).

x represents the number of the

option_name2, option_name2).

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).

In the case of a refund, reversal, or canceled reversal, this variable contains the txn_id of the original transaction, while txn_id contains a new ID for the new transaction.

Character length and limitations: 17 Time/Date stamp generated by PayPal [format: “18:30:30 Jan 1, 2000 PST”]

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 happens 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.

In-Progress: The transaction is in process of authorization and capture. Partially-Refunded: The transaction has been partially refunded. Pending: The payment is pending. See

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

“pending_ reason” on page 45 for

ReasonCode element.

Processed: A payment has been accepted. Voided: This authorization has been voided.

44 August 2005

ABLE A.3 IPN and PDT Variables: Shopping Cart Information

Variable Name Possible Values Description

IPN and PDT Variables

Shopping Cart Information

payment_ type

pending_ reason

echeck instant

address authorization echeck intl multi-currency unilateral upgrade verify other

echeck: This payment was funded with an eCheck. instant: This payment was funded with PayPal balance, credit card, or

Instant Transfer. 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 Se tExpressCheckoutReque st

and have not yet captured funds. echeck: The payment is pending because it was made by 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.

reason_code chargeback

guarantee buyer-

complain

t refund other

This variable is only set if pa yment_status =Reversed or Re funded. 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.

August 2005 45

IPN and PDT Variables

Currency and Currency Exchange

ABLE A.3 IPN and PDT Variables: Shopping Cart Information

Variable Name Possible Values Description

tax PayPal appends the number of the item (e.g., item_name1, item_name2).

The tax_ to a particular shopping cart item. Because profile tax may apply to other items in the cart, the sum of tax_

txn_id A unique transaction ID generated by the PayPal system.

Character length and limitations: 17

x variable is included only if there was a specific tax amount applied

x might not total to tax.

txn_type cart

send_money web-accept

cart: Transaction created by customer via the PayPal Shopping Cart feature. send-money: Transaction created by customer from the Send Money tab on

the PayPal website. web-accept: Transaction created by customer via Buy Now, Donation, or

Auction Smart Logos.

Currency and Currency Exchange

ABLE A.4 IPN and PDT Variables: Currency and Currency Exchange Information

Variable Name Possible Values Description

exchange_ rate

mc_currency See table of

supported currencies.

mc_fee Transaction fee associated with the payment. mc_gross minus mc_fee will

Exchange rate used if a currency conversion occurred.

For payment IPNs, this is the currency of the payment. For non-payment subscription IPNs, this is the currency of the subscription.

equal 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.

mc_gross Full amount of the customer's payment, before transaction fee is subtracted.

Equivalent to payment_gro ss 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.

mc_handling #

This is the total handling amount associated with the transaction. If this is a shopping cart transaction, see

Variables: Shopping Cart Information” on page 43

mc_shipping #

This is the total shipping amount associated with the transaction. If this is a shopping cart transaction, see

Variables: Shopping Cart Information” on page 43

46 August 2005

Table A.3, “IPN and PDT

for more information.

Table A.3, “IPN and PDT

for more information.

IPN and PDT Variables

ABLE A.4 IPN and PDT Variables: Currency and Currency Exchange Information

Variable Name Possible Values Description

Auctions

payment_fee Transaction-

specific for USD payments only

payment_ gross

Transactionspecific for USD payments only

settle_ amount

settle_ currency

Auctions

USD transaction fee associated with the payment. payment_gross payment_fee

equals the amount deposited into the receiver email account.

minus

Is empty for non-USD payments. This is a legacy field replaced by mc_fee. If this amount is negative, it signifies a refund or reversal, and either of those payment statuses can be for the full or partial amount of the original transaction fee.

Full 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.

ABLE A.5 IPN and PDT Variables: Auctions

Variable Name Possible Values Description

auction_

This is the customer’s auction ID. 64

buyer_id auction_

This is the auction’s close date.

closing_ date

auction_ multi_item

This is the number of items purchased in multi-item auction payments. It allows you to count the mc_gross

payment_gross

for the first IPN you receive from a multi-

item auction (auction_multi_item), since each item from the auction will generate an Instant Payment Notification showing the amount for the entire auction.

for_auction true This is an auction payment—paym ents m ade usi ng Pay f or 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

August 2005 47

IPN and PDT Variables

Mass Payment

TABLE A.6 IPN and PDT Variables: Mass Pay

Variable Name Possible Values Description

masspay_ txn_id_

mc_currency _

mc_fee_

mc_gross_

x Transaction-

payment_ date

payment_fee _

Transactionspecific for multiple currencies

specific for multiple Currencies

specific for Multiple Currencies

Transactionspecific for USD payments only

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

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

If the payment is USD, then the value is the same as that for mc_fee_

x is the record number; if the currency is not USD, then this is an empty string.

x, where

payment_ gross_

Transactionspecific for USD payments

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.

only

payment_ status

Completed Denied Processed

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.

receiver_ email_

For Mass Pay payments, the primary email address of the payment recipient, where

x is the record number the mass pay item

48 August 2005

ABLE A.6 IPN and PDT Variables: Mass Pay

Variable Name Possible Values Description

IPN and PDT Variables

Subscriptions Variables

status_x Completed

Failed Reversed Pending

txn_type masspay This payment was sent via Mass Payment unique_id_

x For Mass Payments, the unique ID from input, where x is the record number.

For Mass Payments, the status of the payment, where x is the record number Completed: The payment has been processed, regardless if this was originally

a unilateral payment Failed: The payment failed because there was not enough funds in the

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.

Pending: This is for unilateral payments that are unclaimed.

This allows the merchant to cross-reference the payment

Subscriptions Variables

Along with other IPN variables, the following variables are included in Subscriptions IPNs.

ABLE A.7 Subscriptions Variables

Possible

Variable

txn_type

subscr_date Start date or cancellation date depending on

Values Description

subscrfailed

subscrcancel

subscrpayment

subscrsignup

subscr-eot subscr-

modify

subscr_signup: subscription sign-up. subscr_cancel: subscription cancellation. subscr_failed: subscription payment failure. subscr_payment: subscription payment. subscr_eot: subscription’s end-of-term. subscr_modify: subscription modif ication.

whether transaction is subscr_signup subscr_cancel.

Character Limit

August 2005 49

IPN and PDT Variables

Subscriptions Variables

ABLE A.7 Subscriptions Variables

Possible

Variable

subscr_ effective

period1 (optional) Trial subscription interval in days,

period2 (optional) Trial subscription interval in days,

period3 Regular subscription interval in days, weeks,

amount1 Amount of payment for trial period 1 for USD

amount2 Amount of payment for trial period 2 for USD

amount3 Amount of payment for regular subscription period

mc_amount1 Amount of payment for trial period 1, regardless of

Values Description

Date when the subscription modification will be effective (only for txn_type = subscr_modify).

weeks, months, years (example: a 4 day interval is “period1: 4 D”).

weeks, months, or years.

months, or years.

payments; otherwise blank (optional).

for USD payments; otherwise blank.

currency (optional).

Character Limit

mc_amount2 Amount of payment for trial period 2, regardless of

currency (optional).

mc_amount3 Amount of payment for regular subscription period,

regardless of currency.

mc_currency See table of

supported currencies.

recurring Indicates whether regular rate recurs (1 is yes,

reattempt Indicates whether reattempts should occur upon

retry_at Date PayPal will retry a failed subscription

recur_times The number of payment installments that will occur

For non-payment subscriptions IPNs (i.e.,

txn_type

modify), this is the currency of the subscription. For payment IPNs, it is the currency of the payment (i.e., txn_type = subscr_payment)

blank is no).

payment failures (1 is yes, blank is no).

payment.

at the regular rate.

= signup, cancel, failed, eot, or

50 August 2005

ABLE A.7 Subscriptions Variables

IPN and PDT Variables

Subscriptions Variables

Possible

Variable

Values Description

username (optional) Username generated by PayPal and

Character Limit

given to subscriber to access the subscription.

password (optional) Password generated by PayPal and given

to subscriber to access the subscription (password will be encrypted).

subscr_id ID generated by PayPal for the subscriber. 19

August 2005 51

IPN and PDT Variables

Subscriptions Variables

Variables for Each Subscription Event

The following table shows which variables are associated and can be included in IPN posts with each subscription event type.

About payment_status and txn_type with Subscription IPN. In IPN messages posted by

Subscription events, the payment_status variable is sent only when a payment occurs. For all other events, the pertiunent variable is txn_type.

TABLE A.8 IPN Variables with Each Subscription Event

Payment

Variable Signup Cancel Modify Basic Information

(USD)

Payment (MultiCurrency ) Failed EOT

business receiver_email

XXXXXXX

receiver_id item_name item_number

XXXXXXX

Advanced and Custom Information

invoice custom option_name1 option_selecti

XXXXXXX

on1 option_name2 option_selecti

XXXXXXX

on2

Transaction Information

payment_status

pending_reason reason_code payment_date txn_id parent_txn_id txn_type

subscr_ signup

subscr_ cancel

subscr_ modify

52 August 2005

subscr_payment subscr_

failed

subscr_ eot

TABLE A.8 IPN Variables with Each Subscription Event

Payment

Variable Signup Cancel Modify

(USD)

Currency and Exchange information

IPN and PDT Variables

Subscriptions Variables

Payment (MultiCurrency ) Failed EOT

mc_gross mc_fee mc_currency settle_amount exchange_rate payment_gross payment_fee

Buyer Information

first_name last_name payer_business

_name address_name address_street address_city address_state

XXXXXXX

XXX

XXXXXXX

XXXXXX

address_zip address_

XXXXXX

country payer_email payer_id payer_status

XXXXXXX

payment_type

Subscription Information

subscr_date

XXX

subscr_ effective

period1

XXX

August 2005 53

IPN and PDT Variables

Dispute Notification Variables

ABLE A.8 IPN Variables with Each Subscription Event

Variable Signup Cancel Modify

Payment (USD)

Payment (MultiCurrency ) Failed EOT

period2 period3 amount1 amount2 amount3 mc_amount1 mc_amount2 recurring reattempt retry_at

recur_times username password subscr_id

XXX

XXXXXXX

Dispute Notification Variables

Variables related to customer dispute cases are detailed in Table A.9, “Dispute Notification

Variables” on page 54.

TABLE A.9 Dispute Notification Variables

Possible

Variable

txn_type

txn_id

54 August 2005

Values Description

new_case

A new case has been registered. The merchant’s original transaction identification number for the

payment from the buyer, against which the case was registered.

ABLE A.9 Dispute Notification Variables

Possible

Variable

Values Description

IPN and PDT Variables

Dispute Notification Variables

case_id

case_type complaint

chargeback

Case identification number. Format:

z complaint: A buyer has logged a complaint through the

PP-nnn-nnn -nnn where n is any numeric character.

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_ date

reason_code

Transactionspecific

Depends on

Date and time case was registered. Format:

HH:mm:ss mon DD, YYYY TZ

where TZ is a three-character time zone. Reason for the case.

value of

case_type

reason_code Values for case_type complaint

non_receipt

not_as_ described

Buyer claims that he did not receive goods or service. Buyer claims that the goods or service received differ from

merchant’s description of the goods or service.

reason_code Values for case_type chargeback

unauthorized

Buyer claims that he did not authorize transaction.

non_receipt

duplicate

merchandise

special

Buyer claims that he did not receive goods or service. Buyer claims that a possible duplicate payment was made to the

merchant. Buyer claims that the received merchandise is unsatisfactory,

defective, or damaged. Some other reason. Usually, special indicates a credit card

processing error for which the merchant is not responsible and for which no debit to the merchant will result. PayPal must review the documentation from the credit card company to determine the nature of the dispute and possibly contact the merchant to resolve it.

August 2005 55

IPN and PDT Variables

PDT-Specific Variables

The following variables apply only to PDT.

TABLE A.10 PDT-Specific Variables

Variable Description

tx Transaction ID/PDT token st Transaction status amt Amount of the transaction cc Currency code cm Custom message

56 August 2005

IPN and PDT Variables

PDT-Specific Variables

August 2005 57

IPN and PDT Variables

PDT-Specific Variables

58 August 2005

Downloadable History Log

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_date 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_name last_name

Order Management Integration Guide August 2005 59

Downloadable History Log Columns and Values

TABLE B.1 Downloadable History Log Columns and Values

Column Heading Description Format

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 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

alphanumeric; 39-character limit

Payment Button Variable

Related IPN Variable

txn_type

60 August 2005 Order Management Integration Guide

Downloadable History Log Columns and Values

TABLE B.1 Downloadable History Log Columns and Values

Column Heading Description Format

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

Payment Button Variable

currency_ code

Related IPN Variable

payment_stat us

pending_reas on

mc_currency settle_

currency exchange_

rate mc_gross

Gross Gross amount of transaction signed decimal

Fee Fee (if applicable) for transaction signed decim al

amount payment_

gross settle_

amount amount1 amount2 amount3

payment_fee mc_fee

Net Net amount of transaction signed decimal Note Note for transaction as entered by

counterparty

alphanumeric; 2000-character limit

From Email Address

Email address of transaction sender alphanumeric;

128-character

payer_email

limit

Order Management Integration Guide August 2005 61

Downloadable History Log Columns and Values

TABLE B.1 Downloadable History Log Columns and Values

Column Heading Description Format

To Email Address Email address of transaction recipient alphanumeric;

128-character limit

Transaction ID PayPal-generated unique transaction IDalphanumeric;

17-character limit

Payment Type Payment type used for transaction:

eCheck Instant

alphanumeric; 27-character limit

PayPal Funds

Counterparty Status Account status of buyer:

International – Unverified International – Verified

alphanumeric; 27-character limit

Unverified Verified

Address Status Status of counterparty’s Shipping

Address. Confirmed

alphanumeric; 14-character limit

Non-confirmed

Payment Button Variable

business receiver_

Related IPN Variable

txn_id

payment_type

payer_status

address_ status

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 Number z Subscription Reference Number

alphanumeric; 128-character limit

alphanumeric; 256-character limit

item_name item_name

item_number item_number

62 August 2005 Order Management Integration Guide

Downloadable History Log Columns and Values

TABLE B.1 Downloadable History Log Columns and Values

Column Heading Description Format

Shipping Amount Specified by buyer in the website

field:

z eBay/Auction Shipping amount

unsigned decimal

Or by seller in any of the following button-creation fields:

z PayPal Shopping Cart Shipping

amount

z Buy Now Shipping amount

Insurance Amount Specified by buyer in the website

field:

z eBay/Auction Insura nce amount

Sales Tax Sales Tax Amount specified in

seller’s button-creation process and

unsigned decimal

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

Name

z Buy Now Option 1 Name

Subscription Option 1 Name

Payment Button Variable

shipping shipping2 handling

tax

on0 option_name1

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 Name z Subscription Option 2 Name

alphanumeric; 30-character limit

alphanumeric; 60-character limit

on1 option_name2

on1

option_selec tion1

Order Management Integration Guide August 2005 63

Downloadable History Log Columns and Values

TABLE B.1 Downloadable History Log Columns and Values

Column Heading Description Format

Option 2 Value Entered by buyer in any of the

following website fields:

z PayPal Shopping Cart Option 2

alphanumeric; 30-character limit

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

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

alphanumeric; 20-character limit

Payment Button Variable

os1

Related IPN Variable

option_ selection2

Item URL URL of eBay/Auction Item

(eBay/Auction-specific)

alphanumeric; 256-character limit

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

following button-creation fields:

z PayPal Shopping Cart Invoice

Number

z Buy Now Invoice 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.

invoice invoice

subscr_id

64 August 2005 Order Management Integration Guide

Downloadable History Log Columns and Values

ABLE B.1 Downloadable History Log Columns and Values

Column Heading Description Format

Custom Number Specified by seller in any of the

alphanumeric

following button-creation fields:

z PayPal Shopping Cart Custom

Number

z Buy Now Custom Number z Subscription Custom Number

Shipping Address Line 1

First line of shipping address as specified by counterparty

alphanumeric; 395-character limit

Shipping Address Line 2

Second line of shipping address as specified by counterparty (if applicable)

Town/City Town/City of shipping address as

alphanumeric; 395-character limit

alphanumeric

specified by counterparty

State/Province/Regi on/County/Territor y/Prefecture/Repub

State/Province/Region/Territory/Pref ecture/Republic of shipping address as specified by counterparty

lic Zip/Postal Code Zip/Postal Code of shipping address

as specified by counterparty

Payment Button Variable

custom custom

Related IPN Variable

address_ street1

address_ street2

address_city

address_stat e

address_zip

Country Country of shipping address as

specified by counterparty

Balance Account balance at time of

transaction. Balance is reported in the currency that transaction was received in

address_ country

signed decimal

Order Management Integration Guide August 2005 65

Downloadable History Log Columns and Values

66 August 2005 Order Management Integration Guide

Country Codes

ISO 3166 Standard Country Codes

PayPal relies on two-character country codes defined by International Standards Organization (ISO) 3166.

TABLE C.1 ISO 3166 Two-Character Country Codes

Country Code

Anguilla AI Argentina AR Australia AU Austria AT Belgium BE Brazil BR Canada CA Chile CL China CN Costa Rica CR Cyprus CY Czech Republic CZ Denmark DK Dominican Republic DO Ecuador EC EE Estonia Finland FI France FR Germany DE Greece GR Hong Kong HK

August 2005 67

Country Codes

ISO 3166 Standard Country Codes

ABLE C.1 ISO 3166 Two-Character Country Codes

Country Code

Hungary HU Iceland IS India IN Ireland IE Israel IL Italy IT Jamaica JM Japan JP Latvia LV Lithuania LT Luxembourg LU Malaysia MY Malta MT Mexico MX Netherlands NL New Zealand NZ Norway NO Poland PL Portugal PT Singapore SG Slovakia SK Slovenia SI South Africa ZA South Korea KR Spain ES Sweden SE Switzerland CH Taiwan TW

68 August 2005

ABLE C.1 ISO 3166 Two-Character Country Codes

Country Code

Thailand TH Turkey TR United Kingdom GB United States US Uruguay UY Venezuela VE

Country Codes

ISO 3166 Standard Country Codes

August 2005 69

Country Codes

ISO 3166 Standard Country Codes

70 August 2005

Index

Symbols

_notify-synch 20 _notify-validate 27

Account Optional and PDT 19 address 45 address_city 40 address_country 40 address_country_code 40 address_name 40 address_state 40 address_street 41 address_zip 41 amount1 50 amount2 50 amount3 50 amt 56 at variable for PDT 20 auction_buyer_id 47 auction_closing_date 47 auction_multi_item 47 auth_amount 43 auth_exp 43 auth_id 43 auth_status 43 authorization 45 Auto Return and PDT 19, 21

case_type 55 cc 56 chargeback 32, 55 claims 32 cm 56 complaint 55 Completed 44 country codes 67 currency codes 13 custom 42

Denied 44 duplicate 55

echeck 45 exchange_rate 4 6 Expired 44

Failed 44 first_name 41 for_auction 47

identity token 19

business 41

Canceled-Reversal 44 cart 46 case_creation_date 55 case_id 55

Order Management Integration Guide August 2005 71

In-Progress 44 instant 45 Instant Payment Notification. See IPN. intl 45 INVALID response 28 invoice 42 IPN 23

INVALID reponse 28 multiple currencies 28 set-up 25

Index

VERIFIED response 28 item_name 41 item_number 41

last_name 41

masspay_txn_id_x 48 mc_amount1 50 mc_amount2 50 mc_amount3 50 mc_currency 29, 46, 50 mc_currency_x 48 mc_fee 29, 46, 47 mc_fee_x 48 mc_gross 29, 46 mc_gross_x 43, 48 mc_handling 46 mc_handling_x 43 mc_shipping 46 mc_shipping_x 43 memo 42 merchandise 55 multi-currency 45 multiple currencies 28

new_case 54 non_receipt 55 not_as_described 55 notification synch 20 notification validation 26, 27 notify_url 26, 27 notify_version 40 num_cart_items 43

option_selection2_x 44 other 45

parent_txn_id 44 Partially-Refunded 44 password 51 payer_business_name 41 payer_email 41 payer_id 41 payer_status 41 Payment Data Transfer

See PDT. payment_ tatus 44 payment_date 44, 48 payment_fee 28, 47 payment_gross 28, 47 payment_status 39, 48 payment_type 45 PayPal-supported currencies 13 PDT 15

activating 18

enabling 18

FAIL response 21

identity token 19

SUCCESS response 21 Pending 44 pending_reason 45 period1 50 period2 50 period3 50 Processed 44

quantity 42

option_name1 42, 44 option_name2 42, 44 option_selection1 42 option_selection1_x 44 option_selection2 43

reason_code 45, 55 ReasonCode 44 reattempt 50 receiver_ email_x 48 receiver_email 42 receiver_id 42 recur_times 50

72 August 2005 Order Management Integration Guide

Index

recurring 50 Refunded 44 remaining_settle 43 residence_country 41 Resolution Center 32 retry_at 50 Reversed 44

send_money 46 settle_amount 47 settle_currency 47 special 55 st 56 subscr_cancel 49 subscr_date 49 subscr_effective 50 subscr_eot 49 subscr_failed 49 subscr_id 51 subscr_modify 49 subscr_payment 49 subscr_signup 49 SUCCESS or FAIL response in PDT 21

verify_sign 40 Voided 44

web 46

tax 43, 46 test_ipn 40 tx 56 tx variable for PDT 20 txn_id 46, 54 txn_type 46, 49, 54

unauthorized 55 unilateral 45 upgrade 45 URL-encoding in IPN data 39 username 51

VERIFIED response 28 verify 45

Order Management Integration Guide August 2005 73

Index

74 August 2005 Order Management Integration Guide

PayPal Order Management - 2005 Integration Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Preface

Email

Introduction

Reporting

Differences between Instant Payment Notification (IPN) and Payment Data Transfer (PDT)

SSL Not Required for IPN

PayPal-Supported Currencies

Payment Data Transfer

How PDT Works

Enabling Payment Data Transfer

Getting and Using the Identity Token

PDT and PayPal Account Optional

PDT Notification Synch

Constructing the POST

PayPal Response to POST

PDT and Auto Return: Messaging to Buyer

Preventing Fraud

Code Samples

How It Works

How IPN POSTs Are Sent

Setting Up IPN

IPN Notification and Notification Validation

Shared Secret Per Transaction or by Profile Setting

Shared Secret Validation

HTTPS Postback to PayPal

Using IPN with Multiple Currencies

payment_gross and payment_fee

Examples of Multi-currency IPN Variables

Dispute Notification

Downloadable History Log

Customizing Your Downloadable History Log

Downloading Your History

Viewing Your Downloaded Log

IPN and PDT Variables

Data Type, Maximum Field Lengths, and URL Encoding

About These Tables of Variables

test_ipn Variable in Sandbox

IPN Variables in All Posts

Buyer Information

Basic Information

Advanced and Custom Information

Shopping Cart Information

Currency and Currency Exchange

Auctions

Mass Payment

Subscriptions Variables

Dispute Notification Variables

PDT-Specific Variables

TABLE B.1 Downloadable History Log Columns and Values

Country Codes

ISO 3166 Standard Country Codes