Paypal Order Management 2008 Integration Guide

Order Management - 2008 - Integration Guide PP_OrderMgmt_IG_2008 Free User Guide for PayPal Software, Manual

2015-07-27

: Paypal Paypal-Order-Management-2008-Integration-Guide-777975 paypal-order-management-2008-integration-guide-777975 paypal pdf

Open the PDF directly: View PDF .
Page Count: 82

Order Management Integration Guide

Order Management

Integration Guide

For Professional Use Only

Currently only available in English.

A usage Professional Uniquement

Disponible en Anglais uniquement pour l’instant.

Last updated: March 2008

PayPal Order Management Integration Guide

Document Number: 100009.en_US-200803

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.

2449, Luxembourg, R.C.S. Luxembourg B 118 349

Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval

of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.

Notice of non-liability:

PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,

implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused

by errors or 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.

Order Management Integration Guide March 2008 3

1Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 9

Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

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

SSL Not Required for IPN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

PayPal-Supported Transactional Currencies . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 2 Payment Data Transfer (PDT) . . . . . . . . . . . . . . . .13

How PDT Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Enabling Payment Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Getting and Using the Identity Token . . . . . . . . . . . . . . . . . . . . . . . . . . 18

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

PDT Notification Synch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

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

PayPal Response to POST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

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

Preventing Fraud. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Sample Code for PDT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

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

About IPN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Setting Up IPN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Activating IPN for Your PayPal Account . . . . . . . . . . . . . . . . . . . . . . . . . 24

Setting Up an IPN-Processing Program . . . . . . . . . . . . . . . . . . . . . . . . . 25

Using IPN Notification Validation to Help Prevent Fraud. . . . . . . . . . . . . . . . . . . 26

Using Shared Secrets for Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Using Postbacks for Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Contents

4March 2008 Order Management Integration Guide

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

payment_gross and payment_fee . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

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

Dispute Notification and Downloadable Dispute Report . . . . . . . . . . . . . . . . . . . 31

Downloadable Dispute Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Chapter 4 Transaction History and Reporting Tools . . . . . . . . . .35

Using Monthly Account Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Searching History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Basic Searching by Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Advanced Searching by Field Value . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Specifying Date Ranges for Basic and Advanced History Search . . . . . . . . . . . . 40

Downloading History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Selecting Which Fields to Include in the Download . . . . . . . . . . . . . . . . . . . 43

Understanding the Status and Life Cycle of Transactions . . . . . . . . . . . . . . . . 46

Reconciling Transactions using the Balance Impact Column . . . . . . . . . . . . . . 46

Reconciling Transactions Using the Net Amount Column . . . . . . . . . . . . . . . . 47

Reporting Disputed Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Programmatic Access to Dispute Report . . . . . . . . . . . . . . . . . . . . . . . . 48

Appendix A IPN and PDT Variables. . . . . . . . . . . . . . . . . . . .51

About These Tables of Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Transaction-Specific 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, Website Payments Pro, and Refund Information . . . . . . . 55

Currency and Currency Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Auctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Mass Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Subscriptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Subscriptions Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Dispute Notification Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Order Management Integration Guide March 2008 5

Contents 1

Miscellaneous and Fee-Related IPN Variables . . . . . . . . . . . . . . . . . . . . . 70

PDT-Specific Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Appendix B Downloadable History Logs . . . . . . . . . . . . . . . . .71

Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79

Contents

6March 2008 Order Management Integration Guide

Order Management Integration Guide March 2008 7

PPreface

This Document

This document describes the PayPal features for managing orders, such as Payment Data

Transfer (PDT), Instant Payment Notification (IPN), and Downloadable History Log.

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

Revision History

TABLE P.1 Revision History

Date Description

March 2008 Corrected the procedure for checking the postback response from PayPal when

performing notification validation of IPNs. See “Using Postbacks for

Validation” on page 27.

January 2008 Added information on how to search for contribution payments in transaction

history and what values the Type column in downloadable history logs carries

for donation activity. See Chapter 4, “Transaction History and Reporting Tools.”

September 2007 Replaced the old PayPal logo in screen shots with the new PayPal logo

August 2007 Added shipping_method to Appendix A, “IPN and PDT Variables”. See the

table of variables for “Website Payments Standard, Website Payments Pro, and

Refund Information” on page 55.

July 2007 Minor bug fixing.

April 2007 Added contact_phone to IPN variables. Added pointer to PayPal Business

Overview page.

October 2006 Details about the Downloadable Dispute Report. Minor additions and

corrections to some variables in Appendix A.

July 2006 Minor correction to values of payment_status IPN variable.

May 2006 Description of the programmatically retrievable Dispute Report. Additional IPN

variable values for txn_type: merch-pmt for the Website Payments Pro monthly

fee and adjustment for a resolved dispute requiring a chargeback.

Revision History

8March 2008 Order Management Integration Guide

Order Management Integration Guide March 2008 9

1Introduction

PayPal offers four payment notification methods for back-end integration:

zEmail

zReporting

zInstant Payment Notification (IPN)

zPayment Data Transfer (PDT)

You will receive an email notification in the following cases:

zSuccessful Payment

zPending Payment

zCancelled Payment

If you do not want to receive payment notifications via email:

1. Click the Profile subtab of the My Account tab.

2. Click the Notifications link in the Account Information column.

3. Find the Payment Notifications heading and clear the I receive PayPal Website

Payments and Instant Purchase checkbox.

4. Click the Save button.

Reporting

PayPal’s Reporting Tools provide you with the information you need to effectively measure

and manage your business. With PayPal’s Reporting Tools, you can:

zAnalyze your revenue sources to better understand your customers’ buying behavior

zAutomate time-consuming bookkeeping tasks

zAccurately settle and reconcile transactions

Available reports:

zMonthly Account Statements: View a summary of all credits and debits that have affected

your account balance each month.

Introduction

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

10 March 2008 Order Management Integration Guide

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

channel and currency.

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

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

various file formats (suitable for financial settlements).

For more information about PayPal's reports, see http://www.paypal.com/cgi-

bin/webscr?cmd=p/xcl/rec/reports-intro-outside.

Differences between Payment Data Transfer (PDT) and Instant

Payment Notification (IPN)

PDT's primary function is to display payment transaction details to buyers when they are

automatically redirected back to your site upon payment completion; however, there are cases

where you will not receive notification of all transactions, such as with pending transactions,

refunds, and reversals. For these reasons, or if you are using this data to fulfill orders, PayPal

strongly recommends that you also enable Instant Payment Notification (IPN).

Both IPN and PDT send back the same data; however, there are several important differences.

PDT:

zIs available only to merchants who integrate PayPal with their websites by using Website

Payments Standard.

zRequires Auto Return to be enabled.

zAuto Return will include an ID that can be used to query PayPal for the complete

transaction details.

zIt is possible to miss a notification if the user closes the browser before the redirection is

complete.

IPN:

zDoes not require Auto Return to be enabled.

zAt the end of the website payment flow, PayPal POSTs the IPN data asynchronously (i.e.

not as part of the website payment flow).

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

Order Management Integration Guide March 2008 11

Introduction

PayPal-Supported Transactional Currencies 1

PayPal-Supported Transactional Currencies

The following currencies are supported by PayPal for use in transactions.

TABLE 1.1 PayPal-Supported Currencies and Currency Codes for Transactions

ISO-4217

Code Currency

AUD Australian Dollar

CAD Canadian Dollar

CHF Swiss Franc

CZK Czech Koruna

DKK Danish Krone

EUR Euro

GBP Pound Sterling

HKD Hong Kong Dollar

HUF Hungarian Forint

JPY Japanese Yen

NOK Norwegian Krone

NZD New Zealand Dollar

PLN Polish Zloty

SEK Swedish Krona

SGD Singapore Dollar

USD U.S. Dollar

Introduction

PayPal-Supported Transactional Currencies

12 March 2008 Order Management Integration Guide

Order Management Integration Guide March 2008 13

2Payment Data Transfer (PDT)

Merchants who use Website Payments Standard can use Payment Data Transfer (PDT) to

display transaction details to buyers who are redirected back to the merchants’ websites after

they complete their payments.

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

Transfer. Auto Return applies to PayPal Website Payments Standard, including Buy

Now, Donation, Subscriptions, Shopping Cart, and Gift Certficate buttons. For more

information about Auto Return, see the PayPal Website Payments Standard Integration

Guide.

How PDT Works

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

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

Buy Now button.

Step 2: Bob is taken to a PayPal Payment Details page which displays the details of the

payment he is about to make.

Payment Data Transfer (PDT)

How PDT Works

14 March 2008 Order Management Integration Guide

Step 3: Bob enters his PayPal account information into the PayPal Login fields.

Step 4: Bob is then taken to a confirmation page that displays the details of his selection,

information about how his automatic payments will be funded, and his shipping information.

He clicks the Pay button to complete the payment.

Order Management Integration Guide March 2008 15

Payment Data Transfer (PDT)

How PDT Works 2

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.

Payment Data Transfer (PDT)

How PDT Works

16 March 2008 Order Management Integration Guide

Step 6: A transaction token is passed to the return URL provided by the Widget Warehouse.

The Widget Warehouse fetches the transaction token and retrieves the transaction details from

PayPal via an HTTP POST. Included in the HTTP post is the identity token that was given to

the Widget Warehouse when PDT was enabled.

For more information about the PDT identity token, see “Getting and Using the Identity

Token” on page 18. For more information about the HTTP POST, see “PDT Notification

Synch” on page 19.

Step 7: The Widget Warehouse's Thank You page appears and displays the transaction

information, again informing Bob that his transaction has been completed and a receipt for the

purchase has been sent to him by email. The page also displays 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 March 2008 17

Payment Data Transfer (PDT)

Enabling Payment Data Transfer 2

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

You can enable PDT from your account profile, and you can enable PDT when you use a

button creation tool on the PayPal website to create payment buttons for Website Payments

Standard.

For more information about enabling PDT from a button creation tool, see the Website

Payments Standard Integration Guide.

To enable PD from your account profile:

Payment Data Transfer (PDT)

Enabling Payment Data Transfer

18 March 2008 Order Management Integration Guide

1. Click the My Account tab.

2. Click the Profile subtab.

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 the Save button.

Getting and Using the Identity Token

When you click the Save button and save your PDT preferences, a message appears at the top

of the page indicating that you have successfully saved your preferences. Your identity token

also appears in this message.

You will need to pass this identity token, along with the transaction token, to PayPal in order to

receive information that confirms that a payment is complete.

Order Management Integration Guide March 2008 19

Payment Data Transfer (PDT)

PDT and PayPal Account Optional 2

For security, the identity token is not sent to you; however, once you have enabled PDT, it

permanently appears below the Payment Data Transfer On/Off radio buttons on the Website

Payments Preferences page.

PDT and PayPal Account Optional

The PayPal Account Optional does not require your customers who are new to PayPal to

create a PayPal account to complete a purchase—they go through an alternate checkout and

have the option to sign up afterward. Customers who already have PayPal accounts will

continue to enjoy the privileges of those accounts, such as payment history and integration

with eBay Auctions, and their checkout experience will remain the same.

This PayPal Account Optional feature is available for Buy Now, Donations, and Shopping

Cart buttons, but not for Subscription buttons.

PayPal Account Optional is enabled by default. If the merchant has turned on Payment Data

Transfer and has not disabled PayPal Account Optional, a new user will not be automatically

directed back to the merchant website, but will be given the option to return. When the buyer

clicks the Continue button, the transaction ID associated with the transaction is sent. The

merchant returns the transaction ID, along with their identity token, and PayPal then sends the

merchant payment information that confirms that the payment is complete. The buyer is

directed back to the merchant site where the transaction information is displayed. However, if

the buyer does not click the Continue button, they will not be directed back to the merchant's

site and PDT will not be initiated.

PDT Notification Synch

After you have activated PDT, every time a buyer makes a website payment and is redirected

to your return URL, a transaction token is sent 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.

Payment Data Transfer (PDT)

PDT Notification Synch

20 March 2008 Order Management Integration Guide

Constructing the POST

Here are the guidelines for constructing the PDT HTTPS POST to PayPal for notification

synch:

1. Your POST must be sent to https://www.paypal.com/cgi-bin/webscr.

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

cmd=_notify-synch

3. You must include the transaction token in the variable tx and the value of the transaction

token received via PayPal’s GET:

tx=value_of_transaction_token

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

token:

at=your_identity_token

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

page 18.

PayPal Response to POST

PayPal responds to the post with a single word on one line in the body of the response:

SUCCESS or FAIL. When you receive a SUCCESS response, the rest of the body of the

response is the transaction details, one per line, in the format key=value where key and value

are both be URL-encoded strings. This response data needs to be parsed appropriately and

then URL-decoded.

Example successful response:

SUCCESS

first_name=Jane+Doe

last_name=Smith

payment_status=Completed

payer_email=janedoesmith%40hotmail.com

payment_gross=3.99

mc_currency=USD

custom=For+the+purchase+of+the+rare+book+Green+Eggs+%26+Ham

...

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

zThe Transaction token is not bad.

zThe ID token is not bad.

zThe tokens have not expired.

Order Management Integration Guide March 2008 21

Payment Data Transfer (PDT)

Preventing Fraud 2

PDT and Auto Return: Messaging to Buyer

With Auto Return, you must display a message on the page displayed by the Return URL that

helps the buyer understand that the payment has been made, that the transaction has been

completed, and that payment transaction details will be sent to the buyer by email. You can

display to your customer whatever payment details you feel are appropriate; however, PayPal

recommends including the following:

zItem name

zAmount paid

zPayer email

zShipping 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.”

Preventing Fraud

In order to prevent fraud, PayPal recommends that your programs verify the following:

ztxn_id is not a duplicate to prevent someone from reusing an old, completed transaction.

zreceiver_email is an email address registered in your PayPal account, to prevent the

payment from being sent to a fraudulent account.

zOther transaction details, such as the item number and price, to confirm that the price has

not been changed.

Sample Code for PDT

Sample code for the following development environments is available on the PayPal website

at https://www.paypal.com/us/cgi-bin/webscr?cmd=p/xcl/rec/pdt-code.

zASP/VBScript

zColdFusion

zPERL

zPHP

Payment Data Transfer (PDT)

Sample Code for PDT

22 March 2008 Order Management Integration Guide

Order Management Integration Guide March 2008 - first technical draft 23

3Instant Payment Notification

(IPN)

Instant Payment Notification (IPN) allows you to integrate PayPal payments with your

website’s back-end operations. IPN provides immediate notification and confirmation of

PayPal payments you receive.

This chapter details IPN in the following sections:

z“About IPN” on page 23

z“Setting Up IPN” on page 24”

z“Using IPN Notification Validation to Help Prevent Fraud” on page 26”

z“Using IPN with Multiple Currencies” on page 28”

z“Dispute Notification and Downloadable Dispute Report” on page 31

About IPN

Instant Payment Notification consists of three parts:

1. A customer pays you.

2. PayPal POSTs FORM variables to a URL you specify that runs a program to process the

variables.

3. You validate the notification.

Instant Payment Notification (IPN)

Setting Up IPN

24 March 2008 - first technical draft Order Management Integration Guide

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 clears, fails, or is denied.

2. PayPal posts HTML FORM variables to a program at a URL you specify. You can specify

this URL either in your Profile or with the notify_url variable on each transaction. This

post is the heart of IPN. Included in the notification is the customer’s payment information

(such as customer name, payment amount). All possible variables in IPN posts are detailed

in . When your server receives a notification, it must process the incoming data.

3. Your server must then validate the notification to ensure that it is legitimate.

Setting Up IPN

Follow these procedures to set up IPN:

z“Activating IPN for Your PayPal Account” on page 24

z“Setting Up an IPN-Processing Program” on page 25

Activating IPN for Your PayPal Account

You can activate IPN for your PayPal account through your account profile. Separately, you

can activate IPN for specific payments by including a notification URL in the programming

code that your website sends to PayPal when people pay you.

Order Management Integration Guide March 2008 - first technical draft 25

Instant Payment Notification (IPN)

Setting Up IPN 3

Activating IPN Through Your Account Profile

When you activate IPN through your account profile, the notification URL that you specify is

used for all your IPNs, You can override the value on specific payment transactions by

including notification URLs in the programming code that your website sends to PayPal when

people pay you.

To activate IPN through your account profile:

1. Log in to your Business or Premier account.

2. Click the Profile subtab.

3. In the Selling Preferences column, click the Instant Payment Notification Preferences

link.

4. Click the Edit button.

5. Select the checkbox to activate IPN.

6. In the Notification URL text box, enter the URL of the program that will receive and

process IPNs

7. Click the Save button.

Activating IPN by Including the Notification URL in Programming Code

You can activate IPN for specific payments by including a notification URL in the

programming code that your website sends to PayPal when people pay you. PayPal sends only

IPNs related to payments that result from the code. PayPal sends them to the URL that you

specified in the code.

For example, if you accept payments from different websites through one PayPal account, you

could include different notification URLs in your programming code to let each website

receive IPNs only for its own payments.

NOTE:Notifcation URLs that you include in programming code override the notification URL

that you may have set in your account profile.

To learn how to include notification URLs in programming code:

zSee the Name-Value Pair API Developer Guide and Reference

– or –

zSee the Website Payments Standard Integration Guide

Setting Up an IPN-Processing Program

The data sent to you by IPN comes as HTML FORM name/value pairs.

Sample code for the following development environments is available on the PayPal website

at http://www.paypal.com/us/cgi-bin/webscr?cmd=p/pdn/ipn-codesamples-pop-outside:

zASP.Net/C#

zASP/VBScript

Instant Payment Notification (IPN)

Using IPN Notification Validation to Help Prevent Fraud

26 March 2008 - first technical draft Order Management Integration Guide

zColdFusion

zJava/JSP

zPerl

zPHP

Using IPN Notification Validation to Help Prevent Fraud

After your server receives an Instant Payment Notification, you must confirm that the

notification is authentic. This is known as notification validation. Performing notification

validation for all the IPNs that you receive helps you and PayPal prevent the kind of fraud that

results from spoofing, or “man-in-the-middle” attacks.

IMPORTANT: If you do not use Encrypted Website Payments (EWP) or shared secret

validation, you must check the price, transaction ID, PayPal receiver email

address and other data sent to you by IPN to ensure that they are correct. By

examining this data, you can avoid being spoofed.

PayPal offers two methods for notification validation:

zUse shared secrets.

PayPal recommends this method because it ensures the validity of the data and decreases

network traffic to and from your website. Use shared secrets for validation if:

– You are not using a shared website hosting service.

– You have enabled SSL on your web server.

– You are using Encrypted Website Payments.

– You use the notify_url variable on each individual payment transaction.

For more information, see “Using Shared Secrets for Validation” on page 26.

zSend a postback to PayPal.

Use postbacks for validation if:

– You rely on a shared website hosting service

– You do not have SSL enabled on your web server

For more information, see “Using Postbacks for Validation” on page 27.

Using Shared Secrets for Validation

You can use shared secrets for IPN notification validation by including them in the

programming code that your website sends to PayPal when people pay you. As an alternative,

can set a shared secret in your account profile.

When your IPN-processing program receives an IPN, it must compare that the shared secret in

the post from PayPal matches the shared secret that you expect for notifications about that

payment. If the secret posted by PayPal does not match the secret that you expect, flag the IPN

for further investigation.

Order Management Integration Guide March 2008 - first technical draft 27

Instant Payment Notification (IPN)

Using IPN Notification Validation to Help Prevent Fraud 3

Including Shared Secrets in Programming Code

If you use shared secrets for IPN notification validation, PayPal recommends that you include

shared secrets in all the programming code that your website sends to PayPal when people pay

you. Add a shared secret variable and value to the value of the notification URL that you

include in your programming code.

Use the following format to specify a shared secret as part of a notification URL in your

programming code:

yourIPNnotificationURL?shared_secret_variable_name=shared_secret_value

where:

yourIPNNotificationURL is the URL where you receive IPNs.

shared_secret_variable_name is any variable name that you want.

shared_secret_value is the shared secret itself.

For example, the value of the notification URL variable might look like this:

https%3A//www.mysite.com/PP-IPN-Validate.cfm?secret=shhhhhhh

NOTE:When you include a shared secret in programming code, the secret is included in IPNs

that are related to payments that result from the code, overriding the shared secret that

you may have set in your account profile.

Setting a Shared Secret in Your Account Profile

If you want to use the same shared secret for notification verification of all IPNs, you can set

the secret in your account profile. PayPal includes the secret you set in all IPNs, except for

payments that result from programming code in which you include shared secrets with the

notification URL variable.

Security Considerations with Shared Secrets for Validation

To ensure the security of the shared secrets in HTML button code that you send to PayPal, use

Encrypted Website Payments (EWP). For more information about EWP, see the Website

Payments Standard Integration Guide.

Shared secrets posted to you by PayPal through IPN are not encrypted; they are in clear text

for easier processing. Therefore, the shared secrets are recorded in the clear in the access logs

of your web server. Be sure to practice proper security for these logs. If you use a web server

hosting service, ensure that your provider practices proper security of your data.

Using Postbacks for Validation

If you cannot use shared secrets for notification validation, you can use postbacks to PayPal,

instead. Your postback must include exactly the same variables and values that you receive in

the IPN posted to your server by PayPal, and they must be in the same order.

Constructing Your Postback

Use these guidelines for constructing your postback to PayPal:.

1. Your postback must be sent to https://www.paypal.com/cgi-bin/webscr.

Instant Payment Notification (IPN)

Using IPN with Multiple Currencies

28 March 2008 - first technical draft Order Management Integration Guide

NOTE:You can implement IPN without SSL, including your postbacks for validation, but

PayPal recommends against doing so.

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

cmd=_notify-validate

3. Your postback must include exactly the same variables and values that you receive in the

IPN from PayPal, and they must be in the same order.

Processing the PayPal Response to Your Postback

PayPal responds to your postbacks with a single word in the body of the response: VERIFIED

or INVALID.

When you receive a VERIFIED postback response, perform the following checks on data in

the IPN:

1. Check that the payment_status is Completed.

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

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

3. Check that the receiver_email is an email address registered in your PayPal account.

4. Check that the price, carried in mc_gross, and the currency, carried in mc_currency, are

correct for the item, carried in item_name or item_number.

After you complete the above checks, notification validation is complete. You can update your

database with the information provided, and you can initiate other appropriate automated

back-end processing.

Handling Invalid Responses to Your Postback

When you receive an INVALID postback response, you should investigate. In some cases,

these responses result from an IPN error, possibly from a change in the IPN format.

To determine if an INVALID response results from an IPN error, first examine your code. Your

postback must include exactly the same variables and values that you receive in the IPN

posted to your server by PayPal, and they must be in the same order.

Using IPN with Multiple Currencies

With multiple currencies, you can accept payments in any of the PayPal-supported currencies

(see “PayPal-Supported Transactional Currencies” on page 11). As a result, your IPN

notifications will then include information about the currency of the payment. The following

overview explains how IPN interacts with multiple currencies.

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.

Order Management Integration Guide March 2008 - first technical draft 29

Instant Payment Notification (IPN)

Using IPN with Multiple Currencies 3

payment_gross and payment_fee

These variables reflect the amount received and corresponding fee of U.S. Dollar (USD)

payments. If the amount received and fee deducted are in a currency other than USD, the

variables will still appear in your IPN, but will have no values in them.

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

These values are absent for non-USD payments so that IPN scripts will not process these

amounts as USD. However, legacy IPN scripts will continue to work as before as long as the

merchant only receives USD payments.

Examples of Multi-currency IPN Variables

IPN notifications that use the payment_gross variable will have the following multi-

currency variables added. The variables mc_gross and mc_fee will not be added to IPN

notifications with txn_type: subscr_signup, subscr_cancel, subscr_modify,

subscr_failed, or subscr_eot.

zmc_gross: Full amount of payment received, before transaction fee.

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

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

zmc_currency: Currency of mc_gross, mc_fee, payment_gross, and payment_fee

amounts. Possible values are detailed in “” on page 10.

zFor subscription IPN notifications, such as signup, cancel, modify, failed, and eot,

mc_currency is the currency of the subscription, rather than the currency of the payment.

Example 1

If a user with a USD balance receives a $100 USD payment, the following variables will be

used for the payment:

zmc_gross = payment_gross

zmc_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

Instant Payment Notification (IPN)

Using IPN with Multiple Currencies

30 March 2008 - first technical draft Order Management Integration Guide

Example 2

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

used for the payment:

zmc_gross and mc_fee have values.

zpayment_gross and payment_fee are blank.

EXAMPLE 3.2 Multi-currency IPN: CAD Payment

payment_status = Completed

payment_gross =

payment_fee =

mc_gross = 100

mc_fee = 3.00

mc_currency = CAD

Example 3

If the account is set to automatically convert payments, these variables will be used to show

the conversion. This example is for a user with a USD balance who receives a payment of 100

GBP:

EXAMPLE 3.3 Multiple-currency IPN: Automatic Conversion of GBP Payment

payment_status = Completed

payment_gross =

payment_fee =

mc_gross = 100

mc_fee = 3.00

mc_currency = GBP

settle_amount = 145.5

settle_currency = USD

exchange_rate = 1.5

Example 4

If a payment received is pending due to pending_reason = multi_currency, the first IPN

received would not have the settle_amount, settle_currency, or exchange_rate.

EXAMPLE 3.4 Multiple-currency IPN: Pending Payment

payment_status = Pending

pending_reason = multi_currency

payment_gross =

mc_gross = 100

mc_currency = GBP

The second IPN contains information about settling the payment. If the payment is accepted

into the account’s primary currency, which is USD in the following example:

EXAMPLE 3.5 Pending - Convert to Primary Currency

payment_status = Completed

Order Management Integration Guide March 2008 - first technical draft 31

Instant Payment Notification (IPN)

Dispute Notification and Downloadable Dispute Report 3

payment_gross =

payment_fee =

mc_gross = 100

mc_fee = 3.00

mc_currency = GBP

settle_amount = 145.5

settle_currency = USD

exchange_rate = 1.5

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

EXAMPLE 3.6 Pending - Accept to Currency Balance

payment_status = Completed

payment_gross =

payment_fee =

mc_gross = 100

mc_fee = 3.00

mc_currency = GBP

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.

Dispute Notification and Downloadable Dispute Report

Buyers can register claims about payments; such claims are called cases. PayPal notifies

merchants about new cases with email and with IPN.

There are two kinds of cases:

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

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

Instant Payment Notification (IPN)

Dispute Notification and Downloadable Dispute Report

32 March 2008 - first technical draft Order Management Integration Guide

The IPN messages for chargebacks resulting from a complaint are asynchronous: the IPN

message for the chargeback can be sent to the merchant before the IPN message relating to the

complaint. You should compare the IPN variable parent_txn_id of all IPN messages to match

the chargeback with the complaint.

IPN variables for cases include the type of case, the reason, and other information about the

case. For details about all variables and their possible values, see “Dispute Notification

Variables” on page 68.

Downloadable Dispute Report

The Downloadable Dispute Report provides details about newly created disputes and changes

in the status of cases already in mid-process. The report is designed for the merchant that

processes payment volumes better handled by programmatic interfaces. Thus, while the report

resembles the Dispute Report available via the Resolution Center on the PayPal site, the

downloadable is different in that it contains all open records (records cannot be filtered) and

the invoice ID, which can use to track dispute cases based on your transaction identifiers.

The report is generated every day based on activity for the previous day. Days in which no

activity occurred create an empty report. Reports are available for seven days, after which the

report is no longer available

The report contains information about all chargebacks and buyer complaints for your account.

This report does not contain information about ACH returns of PayPal-unauthorized

complaints.

First Report

When you are first signed up for the DDR, the report contains:

1. All open Chargebacks, regardless of the date the case was created or the current status of

the case

2. All open Buyer Complaints, regardless of the date the case was created or the current status

of the case

Use this report as a starting point against which you will compare all future reports. If you

want this “first report” re-run, contact your PayPal Account Manager and ask them to generate

a “first day” DDR report.

Subsequent Daily Reports

Reports generated every day following the First DDR report contain information about dispute

activity for your account in the past 24 hours or since the last report was generated, including

the following:

zNew cases

zChanged cases, including cases that are closed

Setup

To use the report you must:

Order Management Integration Guide March 2008 - first technical draft 33

Instant Payment Notification (IPN)

Dispute Notification and Downloadable Dispute Report 3

1. Create a unique user with PayPal’s Multi-User Access feature for downloading reports

– Login to your PayPal account.

– Click the Profile subtab.

– Under the Account Information column, click Multi-User Access.

– Click Add.

– On the Multi-User Access page, enter the requested information into the fields provided.

– Click the checkboxes next to each permission you want the alias to have.

– Click Save.

2. Contact your PayPal Account Manager to sign you up for the report.

3. Write a script to download the report from PayPal.

Scripts

You can automate which details you want to be prioritized in your dispute reports by assigning

values shown in the sample HTML below. You can set the values for day, month, and year.

The uname value is the alias you created with the Multi-User Access feature.

<FORM ACTION=”https://www.paypal.com/us/DISPUTE-REPORT-SCHED-LOGIN”

METHOD=”post”>

<INPUT TYPE=”hidden” NAME=”year” VALUE=”2006”

</FORM>

Additional Set Up

You will receive an email informing you that the report is ready. Be sure to monitor your

primary email address for an email stating the download report is ready. This email contains a

hyperlink to the report, which can you access with a browser. You can also use the email as a

trigger for your script that programmatically retrieves the report.

Instant Payment Notification (IPN)

Dispute Notification and Downloadable Dispute Report

34 March 2008 - first technical draft Order Management Integration Guide

Order Management Integration Guide March 2008 35

4Transaction History and

Reporting Tools

With transaction history and reporting tools, you can access monthly account statements,

search your account history for different kinds payments and transactions, download history to

your local computer, and access reports about disputed transactions.

NOTE:PayPal offers an additional set of reporting tools from the PayPal Business Overview

page. Visit the page, at https://business.paypal.com, to access the PayPal Reporting

User’s Guide and to use the additional reporting tools.

To access the history and tools described here:

1. Log in to your Business or Premier account.

2. Click the History subtab.

The History page appears, as shown in Figure 4.1 , “The History Page.”

Transaction History and Reporting Tools

Using Monthly Account Statements

36 March 2008 Order Management Integration Guide

FIGURE 4.1 The History Page

Using Monthly Account Statements

After you activate monthly account statements, you can view them from the History page.

New statements become available on the 15th of each month, and they remain available online

for up to three months.

To activate monthly account statements:

1. From the My Account Overview page, click the History subtab.

The History page appears.

2. Click the View button.

Order Management Integration Guide March 2008 37

Transaction History and Reporting Tools

Searching History 4

3. On the displayed page, click the Ye s radio button.

4. Click the Save button.

Searching History

There are two ways to search your account history for payments and other activity:

zBasic Searching by Activity: specify a kind of account activity, and specify a date range.

zAdvanced Searching by Field Value: specify a value or a pattern of values in a specific

field, and specify a date range.

Transaction History and Reporting Tools

Searching History

38 March 2008 Order Management Integration Guide

Basic Searching by Activity

From the History page, you can search your transaction history by specifying the kind of

account activity you want to view.

In the Show dropdown menu, select one of the following types of account activity.

TABLE 4.1 Basic Search: Selectable Activity Types

All Activity - Advanced

View

Fee Reversals Open Authorizations:

Sent or Received

All Activity - Simple

View

Subscriptions Shipping PayPal Buyer Credit

Payments Sent or

Received

BillPay Transactions Balance Affecting

Transactions

Donations Sent or

Received

Mass Payments Refunds eChecks

Money Requests Currency Conversions Preapproved Payments

Order Management Integration Guide March 2008 39

Transaction History and Reporting Tools

Searching History 4

The choice All Activity - Simple View is selected by default. You can scroll up the list to

select All Activity - Advanced View, which differs from All Activity - Simple View by

including a Balance column. The Balance column shows an ellipsis (...) for transactions that

do not affect your account balance.

For detailed information on how to specify a date range, see “Specifying Date Ranges for

Basic and Advanced History Search” on page 40.

Advanced Searching by Field Value

From the Search page, you can search your transaction history for a value or a pattern of

values in a specific field.

In the Search For text box, type the value or pattern. From the In dropdown menu, select one

of the following fields.

Funds Added or

Withdrawn

Balance Transfer Gift Certificates

TABLE 4.2 Advanced Transaction Search: Key Fields

Field Matching Criteria

Email The text you enter must exactly match an email address

Transaction ID Exact match

TABLE 4.1 Basic Search: Selectable Activity Types

Transaction History and Reporting Tools

Searching History

40 March 2008 Order Management Integration Guide

For detailed information on how to specify a date range, see “Specifying Date Ranges for

Basic and Advanced History Search” on page 40.

Specifying Date Ranges for Basic and Advanced History Search

You can confine your basic or advanced to search to a specific date range in these ways:

zSelect the Within radio button, and select one of these time frames from the dropdown

menu:

–The Past Day

– The Past Week

– The Past Month

–The Past Year

Last Name Any part of the text you enter can match. For example, the

text mit matches Smith and Mitty

Last Name, First Name Any part of text can match

Receipt ID Exact match

Invoice ID Exact match

Billing Agreement Exact match

Profile ID Exact match

TABLE 4.2 Advanced Transaction Search: Key Fields

Field Matching Criteria

Order Management Integration Guide March 2008 41

Transaction History and Reporting Tools

Downloading History 4

zSelect the From radio button, and specify a date range using the text boxes for the From

and To day, month, and year.

IMPORTANT: The duration of the date range you specify affects how quickly you can view

the search results. The longer the duration, the longer the search results take.

For faster results, narrow the date range.

Downloading History

The Download History page lets you specify a time frame for payments and transactions to

include in downloadable history logs, which are files that you save on your local computer.

You can also specify which fields to include and what file format your want.

To to create a downloadable history log and save it on your computer:

1. In the upper left area of the History page, click the Download My History link.

The Download History page appears.

Transaction History and Reporting Tools

Downloading History

42 March 2008 Order Management Integration Guide

FIGURE 4.2 Download History Page

2. In the upper right area of the History Download page, click the Customize Download

Fields link to select which fields you want to include in your downloadable history log.

For more information, see “Selecting Which Fields to Include in the Download” on

page 43.

3. Specify a Custom Date Range for the history you want to download, and select a File

Type for Download.

Your choices are:

– Comma Delimited – All Activity

– Comma Delimited – Completed Payments

– Comma Delimited – Balance Affecting Payments

– Tab Delimited – All Activity

– Tab Delimited – Completed Payments

– Tab Delimited – Balance Affecting Payments

– Intuit Quicken (.qif file format)

Order Management Integration Guide March 2008 43

Transaction History and Reporting Tools

Downloading History 4

– Intuit QuickBooks (.iif file format)

– or –

Select the Last Download to Present radio button to download transactions that occurred

after the last time you downloaded history, and select a File Type for Download.

Your choices are:

– Comma Delimited – Completed Payments

– Tab Delimited – Completed Payments

– Intuit Quicken (.qif file format)

– Intuit QuickBooks (.iif file format)

4. Select the Include Shopping Cart details checkbox if you want your downloadable history

log to include a row of information for each item associated with shopping cart payments.

5. Click the Download History button.

6. When prompted, select whether to open the downloadable history log or to save it on your

local computer.

Selecting Which Fields to Include in the Download

Downloadable history logs always contains these fields:

zDate, Time, and Timezone

zName

zType, Status and Currency

zGross, Fee, and Net

zFrom Email Address and To Email Address

zTransaction ID and Reference Transaction ID

zReceipt ID

zBalance

For details about these default fields, see Appendix B, “Downloadable History Logs.”

In addition, you can select other fields to include, using the Customize My History

Download page.

To select the optional fields you want to include in downloadable history logs:

Transaction History and Reporting Tools

Downloading History

44 March 2008 Order Management Integration Guide

1. In the upper right area of the History Download page, click the Customize Download

Fields link, as shown below.

2. In the Customize My History Download page, select the checkboxes next to the fields

that you want to include.

Order Management Integration Guide March 2008 45

Transaction History and Reporting Tools

Downloading History 4

FIGURE 4.3 The Customize My History Download Page

For details about these optional fields, see Appendix B, “Downloadable History Logs.”

3. Click the Save button to preserve you choices for future downloadable history logs.

Transaction History and Reporting Tools

Downloading History

46 March 2008 Order Management Integration Guide

Understanding the Status and Life Cycle of Transactions

Each row in a downloadable history log shows a transaction, its status at the time of the

download, and its effect on your balance.

Various types of transaction statuses and scenarios can have a negative, positive, or neutral

balance effect. These statuses include:

zPending

zHeld

zCompleted

zDenied

zCancelled

zReversed

For a complete list of possible transaction statuses, see “Status” on page 73.

Pending to Cleared or Uncleared

When a pending payment, such as an eCheck, clears after the three to four business days, the

transaction status changes from Uncleared to Cleared.

Status of Disputed Transactions

Transactions with a Placed status (for temporary holds) usually involve a customer dispute.

If you are found in favor in a dispute, the transaction will be updated with a new line-item to

indicate a Credit. However, if the opposite is true, the Balance Impact column will not change

from the Debit status for that transaction.

You can generate a dispute report that correlates the transaction to the customer and the reason

for the dispute. For more information, see “Reporting Disputed Transactions” on page 47.

Reconciling Transactions using the Balance Impact Column

The optional Balance Impact column shows the word “Credit” for a positive effect or the word

“Debit” for a negative effect on your PayPal account balance.

Credit

When you receive an instant payment or credit card transaction, the Balance Impact column

indicates a credit. Other possible credits to your account are refunds, reversals and payments

sent but never claimed.

In some cases, a credit line-item can update a debit for a transaction. For example, if you send

a payment initially indicated as a debit, but it is denied by the recipient, a new line-item for

that transaction will indicate a credit.

Debit

Debits are transactions that reduce your available balance. For example, refunded transactions

are recorded as a debit in the Balance Impact column and as completed in the Status column.

Order Management Integration Guide March 2008 47

Transaction History and Reporting Tools

Reporting Disputed Transactions 4

Memo Entries

The Balance Impact column can display a Memo entry for transactions that do not affect your

balance, such as unclaimed or uncleared transactions. These kinds of transactions have no

effect on your balance, because they never becomes completed transactions.

Reconciling Transactions Using the Net Amount Column

The Net Amount of a transaction can aid in faster reconciliation.

In most cases, the Net Amount is the Gross minus Fee. When a History entry is updated (for

example, in the case of a refund), the Net Amount column indicates the current net value of the

transaction on a separate line-item.

FIGURE 4.4 Gross, Fee and Net Amount Calculations from History Log

Reporting Disputed Transactions

With dispute reports, you can focus only on transactions that are disputed by customers for

some reason.

Transaction History and Reporting Tools

Reporting Disputed Transactions

48 March 2008 Order Management Integration Guide

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.

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.

Order Management Integration Guide March 2008 49

Transaction History and Reporting Tools

Reporting Disputed Transactions 4

First DDR Report

When you first sign up for the DDR, the report contains:

zAll open chargebacks, regardless of the date the case was created or the current status of

the case

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

zNew cases created

zCases that were modified, including cases that were closed

Frequency / Archiving

The DDR is generated every day based on activity for the previous day. Days with no activity

will generate an empty report.

PayPal will maintain DDR reports for seven days after which the report will not longer be

available.

Report Set Up

To use the DDR you must:

1. Sign up for the report through your PayPal Account Manager

2. Create a unique user to download the report

3. Write code to download the report from a PayPal server

Step 1. Sign up for the report via PayPal Account Management. Contact your PayPal

Account Manager to sign up for the Downloadable Dispute Report.

Step 2. Create a Unique User on PayPal to Download the Report. To use the DDR, you

must use PayPal’s Multi-User Access feature to create a unique user for downloading reports.

1. Login to your PayPal account.

2. Select the Profile subtab.

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.

Transaction History and Reporting Tools

Reporting Disputed Transactions

50 March 2008 Order Management Integration Guide

5. Select the checkboxes next to each of the choices that you want the alias to have.

6. Click the Save button.

Your new user and alias appear on the Multi-User Access page along with a confirmation

message that you have successfully added a new user to your account.

Step 3. Write Code to Download the Report from the PayPal Server. Write code to

request 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.paypal.com/us/DISPUTE-REPORT-SCHED-LOGIN”

METHOD=”post”>

</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 March 2008 51

IPN and PDT Variables

IPN and PDT variables are case-sensitive. All values are lowercase, except those for

payment_status, which have an initial capital letter.

In addition, values posted by IPN are URL-encoded. For example, a colon in http:// is

encoded as %3A in the IPN post: http%3A//

About These Tables of Variables

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

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, Website Payments Pro, and Refund Information” on page 55

z“Currency and Currency Exchange” on page 60

z“Auctions” on page 62

z“Mass Payment” on page 62

z“Subscriptions” on page 64

z“Dispute Notification Variables” on page 68

z“PDT-Specific Variables” on page 70

Transaction-Specific Variable Values

Unless otherwise indicated in the table column labeled Possible Values, the value of an IPN or

PDT variable is always specific to the transaction whose information is being posted.

test_ipn Variable in Sandbox

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

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

between Sandbox IPN and live IPN.

IPN and PDT Variables

IPN Variables in All Posts

52 March 2008 Order Management Integration Guide

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

Possible

Values Description

Char

Length

address_

city

City of customer’s address. 40

address_

country

Country of customer’s address. 64

address_

country_

code

Two-character ISO 3166 country code 2

address_

name

Name used with address (included when the customer provides a

Gift Address)

128

address_

state

State of customer’s address 40

address_

status

confirmed

unconfirmed

Customer provided a confirmed address.

Customer provided an unconfirmed address.

address_

street

Customer’s street address. 200

address_zip Zip code of customer’s address. 20

first_name Customer’s first name 64

Order Management Integration Guide March 2008 53

IPN and PDT Variables

Basic Information A

Basic Information

last_name Customer’s last name 64

payer_

business_

name

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

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

credits.

127

payer_id Unique customer ID. 13

payer_

status

verified

unverified

Customer has a Verified PayPal account.

Customer has an Unverified PayPal account.

contact_

phone

Customer’s telephone number. 20

residence_

country

Two-character ISO 3166 country code 2

TABLE A.2 IPN and PDT Variables: Basic Information

Variable

Name

Possible

Values Description

Char

Length

business Email address or account ID of the payment recipient (that is, 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.

127

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_name_1, item_name_2, and so forth).

127

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.

127

TABLE A.1 IPN and PDT Variables: Buyer Information

Variable

Name

Possible

Values Description

Char

Length

IPN and PDT Variables

Advanced and Custom Information

54 March 2008 Order Management Integration Guide

Advanced and Custom Information

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_

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.

127

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

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

TABLE A.3 IPN and PDT Variables: Advanced and Custom Information

Variable

Name

Possible

Values Description

Char

Length

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

through variables that are never presented to your customer

255

invoice Passthrough variable you can use to identify your Invoice

Number for this purchase. If omitted, no variable is passed back.

127

memo Memo as entered by your customer in PayPal Website Payments

note field.

255

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, Website Payments

Pro, and Refund Information,” on page 55 for more information.

option_

name_2

Option 2 name as requested by you.

If this is a shopping cart transaction, see Table A.4, “IPN and

PDT Variables: Website Payments Standard, Website Payments

Pro, and Refund Information,” on page 55 for more information.

option_

selection1

Option 1 choice as entered by your customer.

If this is a shopping cart transaction, see Table A.4, “IPN and

PDT Variables: Website Payments Standard, Website Payments

Pro, and Refund Information,” on page 55 for more information.

200

TABLE A.2 IPN and PDT Variables: Basic Information

Variable

Name

Possible

Values Description

Char

Length

Order Management Integration Guide March 2008 55

IPN and PDT Variables

Website Payments Standard, Website Payments Pro, and Refund Information A

Website Payments Standard, Website Payments Pro, and

Refund Information

option_

selection2

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, Website Payments

Pro, and Refund Information,” on page 55 for more information.

200

tax Amount of tax charged on payment.

If this is a shopping cart transaction, see Table A.4, “IPN and

PDT Variables: Website Payments Standard, Website Payments

Pro, and Refund Information,” on page 55 for more information.

TABLE A.4 IPN and PDT Variables: Website Payments Standard, Website Payments Pro, and

Refund Information

Variable

Name

Possible

Values Description

Char

Length

auth_id Transaction-

specific

Authorization identification number 19

auth_exp Transaction-

specific

Authorization expiration date and time, in the following format:

HH:MM:SS DD Mmm YY, YYYY PST

auth_amount Transaction-

specific

Authorization amount

auth_status Completed

Pending

Voided

Status of authorization

mc_gross_xTransaction-

specific for

multiple

currencies

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.

mc_

handling_x

Transaction-

specific for

multiple

currencies

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

TABLE A.3 IPN and PDT Variables: Advanced and Custom Information

Variable

Name

Possible

Values Description

Char

Length

IPN and PDT Variables

Website Payments Standard, Website Payments Pro, and Refund Information

56 March 2008 Order Management Integration Guide

mc_

shipping_x

Transaction-

specific for

multiple

currencies

This is the combined total of shipping and shipping2

Website Payments Standard 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 shippingx

might not be equal to shipping.

num_cart_

items

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

cart.

option_

name1

PayPal appends the number of the item where x represents the

number of the shopping cart detail item (e.g., option_name1,

option_name2).

option_

name2

PayPal appends the number of the item where x represents the

number of the shopping cart detail item (e.g., option_name2,

option_name2).

option_

selection1_

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

option_selection1, option_selection2), where x

represents the number of the shopping cart detail item.

200

option_

selection2_

PayPal appends the number of the item where x represents the

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

option_selection1, option_selection2).

200

parent_txn_

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.

payment_

date

Time/Date stamp generated by PayPal, in the following format:

HH:MM:SS DD Mmm YY, YYYY PST

TABLE A.4 IPN and PDT Variables: Website Payments Standard, Website Payments Pro, and

Refund Information

Variable

Name

Possible

Values Description

Char

Length

Order Management Integration Guide March 2008 57

IPN and PDT Variables

Website Payments Standard, Website Payments Pro, and Refund Information A

payment_

status

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

Pending: The payment is pending. See pending_reason for

more information.

Refunded: You refunded the payment.

Reversed: A payment was reversed due to a chargeback or

other type of reversal. The funds have been removed from your

account balance and returned to the buyer. The reason for the

reversal is specified in the ReasonCode element.

Processed: A payment has been accepted.

Voided: This authorization has been voided.

payment_

type

echeck

instant

echeck: This payment was funded with an eCheck.

instant: This payment was funded with PayPal balance, credit

card, or Instant Transfer.

TABLE A.4 IPN and PDT Variables: Website Payments Standard, Website Payments Pro, and

Refund Information

Variable

Name

Possible

Values Description

Char

Length

IPN and PDT Variables

Website Payments Standard, Website Payments Pro, and Refund Information

58 March 2008 Order Management Integration Guide

pending_

reason

address

authorizati

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

TABLE A.4 IPN and PDT Variables: Website Payments Standard, Website Payments Pro, and

Refund Information

Variable

Name

Possible

Values Description

Char

Length

Order Management Integration Guide March 2008 59

IPN and PDT Variables

Website Payments Standard, Website Payments Pro, and Refund Information A

reason_code chargeback

guarantee

buyer_

complaint

refund

other

This variable is set if payment_status =Reversed,

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

Transaction-

specific

Remaining amount that can be captured with Authorization and

Capture

shipping_

method

Merchant-

specific

The name of a shipping method from the Shipping Calculations

section of the merchant's account profile. The buyer selected the

named shipping method for this transaction.

shipping Transaction-

specific

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.

transaction

_entity

auth

reauth

order

payment

Authorization and Capture transaction entity

txn_id A unique transaction ID generated by PayPal. 19

TABLE A.4 IPN and PDT Variables: Website Payments Standard, Website Payments Pro, and

Refund Information

Variable

Name

Possible

Values Description

Char

Length

IPN and PDT Variables

Currency and Currency Exchange

60 March 2008 Order Management Integration Guide

Currency and Currency Exchange

txn_type cart

express_

checkout

send_money

virtual_

terminal

web-accept

cart: Transaction created by a customer:

zVia the PayPal Shopping Cart feature.

zVia Express Checkout when the cart contains multiple 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.

NOTE:In some cases, txn_type is blank when the variable

reason_code is chargeback.

TABLE A.5 IPN and PDT Variables: Currency and Currency Exchange Information

Variable

Name

Possible

Values Description

Char

Length

exchange_

rate

Exchange rate used if a currency conversion occurred.

mc_currency Three-

character

currency code.

See table of

supported

currencies.

For payment IPN notifications, this is the currency of the

payment. For non-payment subscription IPN notifications, this is

the currency of the subscription.

mc_fee Transaction fee associated with the payment. mc_gross minus

mc_fee equals the amount deposited into the receiver_email

account. Equivalent to payment_fee for USD payments. If this

amount is negative, it signifies a refund or reversal, and either of

those payment statuses can be for the full or partial amount of the

original transaction fee.

TABLE A.4 IPN and PDT Variables: Website Payments Standard, Website Payments Pro, and

Refund Information

Variable

Name

Possible

Values Description

Char

Length

Order Management Integration Guide March 2008 61

IPN and PDT Variables

Currency and Currency Exchange A

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

subtracted. Equivalent to payment_gross for USD payments.

If this amount is negative, it signifies a refund or reversal, and

either of those payment statuses can be for the full or partial

amount of the original transaction.

mc_handling

Total handling amount associated with the transaction.

If this is a shopping cart transaction, see Table A.4, “IPN and

PDT Variables: Website Payments Standard, Website Payments

Pro, and Refund Information,” on page 55 for more information.

mc_shipping

Total shipping amount associated with the transaction.

If this is a shopping cart transaction, see Table A.4, “IPN and

PDT Variables: Website Payments Standard, Website Payments

Pro, and Refund Information,” on page 55 for more information.

payment_fee Transaction-

specific for

USD payments

only

USD transaction fee associated with the payment.

payment_gross minus payment_fee equals the amount

deposited into the receiver email account. Is empty for non-USD

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

payment_

gross

Transaction-

specific for

USD payments

only

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.

settle_

amount

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

settle_

currency

Three-

character

currency code.

See table of

supported

currencies.

Currency of settle_amount.

TABLE A.5 IPN and PDT Variables: Currency and Currency Exchange Information

Variable

Name

Possible

Values Description

Char

Length

IPN and PDT Variables

Auctions

62 March 2008 Order Management Integration Guide

Auctions

Mass Payment

TABLE A.6 IPN and PDT Variables: Auctions

Variable

Name

Possible

Values Description

Char

Length

auction_

buyer_id

The customer’s auction ID. 64

auction_

closing_

date

The auction’s close date, in the following format: HH:MM:SS

DD Mmm YY, YYYY PST

auction_

multi_item

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.

for_auction true This is an auction payment—payments made using Pay for eBay

Items or Smart Logos—as well as Send Money/Money Request

payments with the type eBay items or Auction Goods (non-

eBay).

TABLE A.7 IPN and PDT Variables: Mass Payment

Variable

Name

Possible

Values Description

Char

Length

masspay_

txn_id_x

For Mass Payments, a unique transaction ID generated by the

PayPal system, where x is the record number of the mass pay

item

mc_currency

Transaction-

specific for

multiple

currencies

For Mass Payments, the currency of the amount and fee, where x

is the record number the mass pay item

mc_fee_xTransaction-

specific for

multiple

Currencies

For Mass Payments, the transaction fee associated with the

payment, where x is the record number the mass pay item

Order Management Integration Guide March 2008 63

IPN and PDT Variables

Mass Payment A

mc_gross_xTransaction-

specific for

Multiple

Currencies

The gross amount for the amount, where x is the record number

the mass pay item

payment_

date

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

payment_fee

Transaction-

specific for

USD payments

only

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

mc_fee_x, where x is the record number; if the currency is not

USD, then this is an empty string.

NOTE:This is a deprecated field. Use mc_fee_x instead.

payment_

gross_x

Transaction-

specific for

USD payments

only

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.

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.

reason_code 1001

1003

1004

This variable is only set if status = Failed.

1001: Invalid UserID.

1003: Country of Residence check failure

1004: Country of Funding Source check failure

receiver_

email_x

For Mass Payments, the primary email address of the payment

recipient, where x is the record number of the mass pay item

127

status_xCompleted

Failed

Reversed

Unclaimed

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.

TABLE A.7 IPN and PDT Variables: Mass Payment

Variable

Name

Possible

Values Description

Char

Length

IPN and PDT Variables

Subscriptions

64 March 2008 Order Management Integration Guide

Subscriptions

Subscriptions Variables

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

txn_type masspay This payment was sent via Mass Payment

unique_id_xFor Mass Payments, the unique ID from input, where x is the

record number. This allows the merchant to cross-reference the

payment

TABLE A.1 Subscriptions Variables

Variable

Possible

Values Description Char Limit

txn_type subscr-

failed

subscr-

cancel

subscr-

payment

subscr-

signup

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

subscr_date Start date or cancellation date depending on

whether transaction is subscr_signupor

subscr_cancel.

Time/Date stamp generated by PayPal , in the

following format: HH:MM:SS DD Mmm YY,

YYYY PST

subscr_

effective

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

TABLE A.7 IPN and PDT Variables: Mass Payment

Variable

Name

Possible

Values Description

Char

Length

Order Management Integration Guide March 2008 65

IPN and PDT Variables

Subscriptions A

period1 (optional) Trial subscription interval in days,

weeks, months, years (example: a 4 day interval is

“period1: 4 D”).

period2 (optional) Trial subscription interval in days,

weeks, months, or years.

period3 Regular subscription interval in days, weeks,

months, or years.

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

mc_amount3 Amount of payment for regular subscription period,

regardless of currency.

mc_currency See table of

supported

currencies.

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

txn_type= signup, 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)

recurring Indicates whether regular rate recurs (1 is yes,

blank is no).

reattempt Indicates whether reattempts should occur upon

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

retry_at Date PayPal will retry a failed subscription

payment.

recur_times The number of payment installments that will occur

at the regular rate.

username (optional) Username generated by PayPal and

given to subscriber to access the subscription.

password (optional) Password generated by PayPal and given

to subscriber to access the subscription (password

will be encrypted).

TABLE A.1 Subscriptions Variables

Variable

Possible

Values Description Char Limit

IPN and PDT Variables

Subscriptions

66 March 2008 Order Management Integration Guide

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.

subscr_id ID generated by PayPal for the subscriber. 19

TABLE A.2 IPN Variables with Each Subscription Event

Variable Signup Cancel Modify

Payment

(USD)

Payment

(Multi-

Currency) Refund Failed EOT

Basic Information

business X XXX X XX

receiver_email X XXX X XX

receiver_id XX

item_name X XXX X XX

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

option_selecti

on1

X XXX X XX

option_name2 X XXX X XX

option_selecti

on2

X XXX X XX

Transaction Information

payment_status XX X

pending_reason XX

reason_code XX

TABLE A.1 Subscriptions Variables

Variable

Possible

Values Description Char Limit

Order Management Integration Guide March 2008 67

IPN and PDT Variables

Subscriptions A

payment_date XX

txn_id XX

parent_txn_id XX

txn_type subscr_

signup

subscr_

cancel

subscr_

modify

subscr_payment subscr_

failed

subscr

eot

Currency and Exchange information

mc_gross XX

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

last_name X XXX X XX

payer_business

_name

X XXX X X

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_

country

X XXX X X

payer_email X XXX X XX

payer_id X XXX X XX

payer_status X XXX X XX

payment_type XX

TABLE A.2 IPN Variables with Each Subscription Event

Variable Signup Cancel Modify

Payment

(USD)

Payment

(Multi-

Currency) Refund Failed EOT

IPN and PDT Variables

Dispute Notification Variables

68 March 2008 Order Management Integration Guide

Dispute Notification Variables

Subscription Information

subscr_date XXX

subscr_

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

recur_times XXX

username X XXX X XX

password X XXX X XX

subscr_id X XXX X XX

TABLE A.8 Dispute Notification Variables

Variable

Possible

Values Description

txn_type new_case

adjustment

new_case: A new case has been registered.

adjustment: A case has been resolved and closed.

TABLE A.2 IPN Variables with Each Subscription Event

Variable Signup Cancel Modify

Payment

(USD)

Payment

(Multi-

Currency) Refund Failed EOT

Order Management Integration Guide March 2008 69

IPN and PDT Variables

Dispute Notification Variables A

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

zcomplaint: A buyer has logged a complaint through the

PayPal Resolution Center.

zchargeback: A buyer has filed a chargeback with his credit

card company, which has notified PayPal of the reason for the

chargeback.

case_

creation_

date

Transaction-

specific

Date and time case was registered, in the following format:

HH:MM:SS DD Mmm YY, YYYY PST

reason_code Depends on

value of

case_type

Reason for the case.

Values for case_type set to complaint:

znon_receipt: Buyer claims that he did not receive goods or

service.

znot_as_described: Buyer claims that the goods or service

received differ from merchant’s description of the goods or

service.

Values for case_type set to chargeback:

zunauthorized

zadjustment_reimburse: A case that has been resolved

and close requires a reimbursement.

znon_receipt: Buyer claims that he did not receive goods or

service.

zduplicate: Buyer claims that a possible duplicate payment

was made to the merchant.

zmerchandise: Buyer claims that the received merchandise

is unsatisfactory, defective, or damaged.

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

TABLE A.8 Dispute Notification Variables

Variable

Possible

Values Description

IPN and PDT Variables

PDT-Specific Variables

70 March 2008 Order Management Integration Guide

Miscellaneous and Fee-Related IPN Variables

PDT-Specific Variables

The following variables apply only to PDT.

TABLE A.9 Miscellaneous and Fee-Related IPN Variables

Variable

Name

Possible

Values Description

Char

Length

txn_type merch-pmt Monthly fee for use of Website Payments Pro 64

TABLE A.10 PDT-Specific Variables

Variable Description

amt Amount of the transaction

cc Currency code

cm Custom message

sig

st Transaction status

tx Transaction ID/PDT token

Order Management Integration Guide March 2008 71

Downloadable History Logs

TABLE B.1 Fields and Values in Downloadable History Logs

Field Name Description Format

Payment

Button

Variable

Related IPN

Variable

Date Date transaction was initiated

(according to PayPal system time,

US-Pacific time zone).

Log sorted in reverse chronological

order by Date (most recent first)

[M]M/[D]D/Y

YYY

payment_dat

subscr_date

Time Time transaction was initiated

(according to PayPal system time,

US-Pacific time zone).

HH:MM:SS

Timezone The time zone used for recording

transactions in your PayPal account.

Alphanumeric;

three-character

codes

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

Downloadable History Logs

72 March 2008 Order Management Integration Guide

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

Donation Received

Donation Sent

eCheck Received

eCheck Sent

Funds Added with a Personal Check

Guarantee Reimbursement

Payment Received

Payment Sent

PayPal

PayPal Balance Adjustment

Referral Bonus

Refund

Shopping Cart Item

Shopping Cart Payment Received

Shopping Cart Payment Sent

Subscription Payment Received

Subscription Payment Sent

Transfer Update to Add Funds from a

Bank Account

Update to Debit Card Credit

Update to eCheck Received

Update to Payment Received

Update to Payment Sent

continued...

alphanumeric;

39-character

limit

txn_type

TABLE B.1 Fields and Values in Downloadable History Logs

Field Name Description Format

Payment

Button

Variable

Related IPN

Variable

Order Management Integration Guide March 2008 73

Downloadable History Logs B

Type (continued) Update to Reversal

Update to Web Accept Payment

Received

Virtual Debit Card Authorization

Virtual Debit Card Credit Received

Virtual Debit Card Purchase

Virtual Debt Card Credit Received

Web Accept Payment Received

Web Accept Payment Sent

Withdraw Funds to a Bank Account

Status Status of transaction at time of

download:

Canceled

Cleared

Completed

Denied

Expired

Failed

Pending

Refunded

Returned

Reversed

Unclaimed

Uncleared

alphanumeric;

10-character

limit

payment_

status

pending_

reason

Subject Subject of transaction as entered by

counterparty

alphanumeric;

256-character

limit

Currency Currency of transaction alphanumeric;

three character

limit

currency_

code

mc_currency

settle_

currency

exchange_

rate

mc_gross

TABLE B.1 Fields and Values in Downloadable History Logs

Field Name Description Format

Payment

Button

Variable

Related IPN

Variable

Downloadable History Logs

74 March 2008 Order Management Integration Guide

Gross Gross amount of transaction signed decimal amount payment_

gross

settle_

amount

amount1

amount2

amount3

Fee Fee (if applicable) for transaction signed decimal 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

limit

payer_email

To Email Address Email address of transaction recipient alphanumeric;

128-character

limit

business receiver_

Transaction ID PayPal-generated unique transaction

alphanumeric;

17-character

limit

txn_id

Payment Type Payment type used for transaction:

eCheck

Instant

PayPal Funds

alphanumeric;

27-character

limit

payment_typ

Counterparty Status Account status of buyer:

International – Unverified

International – Verified

Unverified

Verified

alphanumeric;

27-character

limit

payer_statu

Address Status Status of counterparty’s Shipping

Address.

Confirmed

Non-confirmed

alphanumeric;

14-character

limit

address_

status

TABLE B.1 Fields and Values in Downloadable History Logs

Field Name Description Format

Payment

Button

Variable

Related IPN

Variable

Order Management Integration Guide March 2008 75

Downloadable History Logs B

Item Title Specified by buyer in the website

field:

zAuction/Item Title

Or by seller in any of the following

button-creation fields:

zPayPal Shopping Cart Item Name

zBuy Now Item Name

zDonations Item Name

zSubscriptions Name

alphanumeric;

128-character

limit

item_name item_name

Item ID Specified by buyer in the website

field:

zAuction/Item Number

Or by seller in any of the following

button-creation fields:

zPayPal Shopping Cart Item

Number

zBuy Now ID Number

zDonations ID Number

zSubscription Reference Number

alphanumeric;

256-character

limit

item_number item_number

Shipping Amount Specified by buyer in the website

field:

zeBay/Auction Shipping amount

Or by seller in any of the following

button-creation fields:

zPayPal Shopping Cart Shipping

amount

zBuy Now Shipping amount

unsigned

decimal

shipping

shipping2

handling

Insurance Amount Specified by buyer in the website

field:

zeBay/Auction Insurance amount

unsigned

decimal

Sales Tax Sales Tax Amount specified in

seller’s button-creation process and

Profile preferences

unsigned

decimal

tax

Option 1 Name Specified by seller in any of the

following button-creation fields:

zPayPal Shopping Cart Option 1

Name

zBuy Now Option 1 Name

zSubscription Option 1 Name

alphanumeric;

60-character

limit

on0 option_name

TABLE B.1 Fields and Values in Downloadable History Logs

Field Name Description Format

Payment

Button

Variable

Related IPN

Variable

Downloadable History Logs

76 March 2008 Order Management Integration Guide

Option 1 Value Entered by buyer in any of the

following website fields:

zPayPal Shopping Cart Option 1

Val ue

zBuy Now Option 1 Value

zSubscription Option 1 Value

Or specified by seller in any of the

following button-creation fields:

zPayPal Shopping Cart Value 1

Choices

zBuy Now Value 1 Choices

zSubscription Value 1 Choices

alphanumeri

c; 30-

character

limit

on1 option_name

Option 2 Name Specified by seller in any of the

following button-creation fields:

zPayPal Shopping Cart Option 2

Name

zBuy Now Option 2 Name

zSubscription Option 2 Name

alphanumeric;

60-character

limit

on1 option_

selection1

Option 2 Value Entered by buyer in any of the

following website fields:

zPayPal Shopping Cart Option 2

Val ue

zBuy Now Option 2 Value

zSubscription Option 2 Value

Or specified by seller in any of the

following button-creation fields:

zPayPal Shopping Cart Value 2

Choices

zBuy Now Value 2 Choices

zSubscription Value 2 Choices

alphanumeric;

30-character

limit

os1 option_

selection2

Auction Site Name of Auction Site:

zeBay

zYahoo! Auctions

zuBid.com

zAmazon.com Auctions

zMSN Auctions

zBidVille

zOther

alphanumeric;

20-character

limit

Item URL URL of eBay/Auction Item

(eBay/Auction-specific)

alphanumeric;

256-character

limit

TABLE B.1 Fields and Values in Downloadable History Logs

Field Name Description Format

Payment

Button

Variable

Related IPN

Variable

Order Management Integration Guide March 2008 77

Downloadable History Logs B

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

following button-creation fields:

zPayPal Shopping Cart Invoice

Number

zBuy Now Invoice Number

zSubscription Invoice Number

alphanumeric invoice invoice

Subscription

Number

PayPal-generated Subscription

Transaction ID Number

S-xxxxxxxxxxxxxxxx

where x is the transaction ID.

alphanumeric;

19-character

limit

subscr_id

Custom Number Specified by seller in any of the

following button-creation fields:

zPayPal Shopping Cart Custom

Number

zBuy Now Custom Number

zSubscription Custom Number

alphanumeric custom custom

Shipping Address

Line 1

First line of shipping address as

specified by counterparty

alphanumeric;

395-character

limit

address_

street1

Shipping Address

Line 2

Second line of shipping address as

specified by counterparty (if

applicable)

alphanumeric;

395-character

limit

address_

street2

Town/City Town/City of shipping address as

specified by counterparty

alphanumeric address_cit

State/Province/Regi

on/County/Territor

y/Prefecture/Repub

lic

State/Province/Region/Territory/Prefe

cture/Republic of shipping address as

specified by counterparty

address_

state

Zip/Postal Code Zip/Postal Code of shipping address

as specified by counterparty

address_zip

Country Country of shipping address as

specified by counterparty

address_

country

TABLE B.1 Fields and Values in Downloadable History Logs

Field Name Description Format

Payment

Button

Variable

Related IPN

Variable

Downloadable History Logs

78 March 2008 Order Management Integration Guide

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

TABLE B.1 Fields and Values in Downloadable History Logs

Field Name Description Format

Payment

Button

Variable

Related IPN

Variable

Order Management Integration Guide March 2008 79

Index

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 39

amount1 65

amount2 65

amount3 65

amt 70

auction_buyer_id 62, 70

auction_closing_date 62

auction_multi_item 62

AUD 11

Australian Dollar 11

auth_amount 55

auth_exp 55

auth_id 55

auth_status 55

authorization 58

Balance 39

business 53

CAD 11

Canadian Dollar 11

Canceled-Reversal 57

cart 60

case_creation_date 69

case_id 69

case_type 69

cc 70

chargeback 69

CHF 11

cm 70

complaint 69

Completed 55, 57

contact_phone 53

currency codes 11

custom 54

Czech Koruna 11

CZK 11

Danish Krone 11

Denied 57

DKK 11

downloadable history logs 7, 41

duplicate 69

echeck 57, 58

EUR 11

Euro 11

exchange_rate 60

Expired 57

express_checkout 60

Failed 57

first_name 52

for_auction 62

Forint 11

fraud prevention 26

GBP 11

Index

80 March 2008 Order Management Integration Guide

History 35

HKD 11

Hong Kong Dollar 11

HUF 11

Hungarian Forint 11

iif file format 43

instant 57

intl 58

invoice 54

item_name 53

item_number 53

Japanese Yen 11

JPY 11

Koruna 11

Krona 11

Krone 11

last_name 53

logs 7, 41

masspay_txn_id_x 62

mc_amount1 65

mc_amount2 65

mc_amount3 65

mc_currency 60, 65

mc_currency_x 62

mc_fee 60, 61, 63

mc_fee_x 62, 63

mc_gross 61

mc_gross_x 55, 63

mc_handling 61

mc_handling_x 55

mc_shipping 61

mc_shipping_x 56

memo 54

merchandise 69

merch-pmt 70

multi-currency 58

Net Amount 47

New Zealand Dollar 11

new_case 68

NOK 11

non_receipt 69

Norwegian Krone 11

not_as_described 69

notification 24

notification URL 24, 25

notification validation 26

notify_version 52

num_cart_items 56

NZD 11

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

parent_txn_id 56

password 65

payer_business_name 53

payer_email 53

payer_id 53

payer_status 53

payment_ tatus 57

payment_date 56, 63

payment_fee 61

payment_fee_x 63

Order Management Integration Guide March 2008 81

Index

payment_gross 61

payment_gross_x 63

payment_status 51, 63

payment_type 57

PayPal-supported currencies 11

Pending 55, 57

pending_reason 58

period1 65

period2 65

period3 65

PLN 11

Polish Zloty 11

Pound Sterling 11

Processed 57

qif file format 42, 43

quantity 54

QuickBooks 43

Quicken 42, 43

reason_code 59, 63, 69

ReasonCode 57

reattempt 65

receiver_ email_x 63

receiver_email 53, 54

receiver_id 54

recur_times 65

recurring 65

Refunded 57

remaining_settle 59

residence_country 53

retry_at 65

Reversed 57

SEK 11

send_money 60

settle_amount 61

settle_currency 61

SGD 11

shipping 59

sig 70

Singapore Dollar 11

special 69

st 70

status_x 63

subscr_cancel 64

subscr_date 64

subscr_effective 64

subscr_eot 64

subscr_failed 64

subscr_id 66

subscr_modify 64

subscr_payment 64

subscr_signup 64

Swedish Krona 11

Swiss Franc 11

tax 55, 59

test_ipn 51

transaction_entity 59

tx 70

txn_id 59, 69

txn_type 60, 64, 68

U.S. Dollar 11

unauthorized 69

unilateral 58

unique_id_x 64

upgrade 58

URL-encoding in IPN data 51

USD 11

username 65

verify 58

verify_sign 52

virtual_terminal 60

Voided 55, 57

web 60

Index

82 March 2008 Order Management Integration Guide

Yen 11

Zloty 11

Paypal Order Management 2008 Integration Guide

Order Management - 2008 - Integration Guide PP_OrderMgmt_IG_2008 Free User Guide for PayPal Software, Manual

Navigation menu

Versions of this User Manual:

Views

Navigation