PayPal Order Management - 2005 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: August 2005

PayPal Order Management Integration Guide

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

Notice of Non-Liability

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

Contents

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Order Management Integration Guide August 2005 3

Contents

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Appendix B Downloadable History Log

Columns and Values 59

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

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

4 August 2005 Order Management Integration Guide

List of Tables

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

Amounts 13

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

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

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

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

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

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

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

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

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

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

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

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

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

Order Management Integration Guide August 2005 5

List of Tables

6 August 2005 Order Management Integration Guide

List of Figures

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

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

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

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

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

Order Management Integration Guide August 2005 7

List of Figures

8 August 2005 Order Management Integration Guide

Preface

This Document

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

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

Intended Audience

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

Organization of This Document

Chapter 1, “Introduction,” gives a brief overview of the PayPal features for order management

discussed in this guide.

Chapter 2, “Payment Data Transfer,” describes how PDT works and how to set it up. Chapter 3, “Instant Payment Notification (IPN) ,” describes how IPN works and how to set it

up.

Chapter 4, “Downloadable History Log,” describes the Downloadable History Log and how

you can use it to reconcile payment transactions.

Appendix A, “IPN and PDT Variables,” is a detailed description of all variables and values

returned by IPN or PDT.

Appendix B, “Downloadable History Log Columns and Values,” describes the columns and

values that can be included in the Downloadable History Log.

Notational Conventions

This document uses typefaces to identify the characteristics of text. These typefaces and the characteristics they imply are described below:

Typeface How Used

serif italics A document title.

A term being discussed or defined. For example: A file is a readable or writable stream of characters …

Boolean values (not keywords). For example: The function returns true if it encounters an error.

Order Management Integration Guide August 2005 9

Preface

Typeface How Used

monospaced

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

San-serif oblique

Pathnames or file names that appear in body text frames.

Code-related names that appear in body text frames. Such names are used for functions, callbacks, arguments, data structures, and fields.

For example: AbstractResponseType is the SOAP response type definition on which all PayPal API response methods are based.

Components of Internet protocol requests and responses, such as HTTPS and FORM variables.

For example: The PayPal system uses a method=POST request to return IPN status variables related to subscriptions, such as txn_type.

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

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

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

amount_

is the item amount for the third item in a multiple-item shopping cart.

X is the name of the variable for a multi-item shopping cart. amount_3

To convey additional information, this document may also apply color and underlining to words or phrases that use the typefaces described above. Such use is described below:

Text attribute How Used

xxxxxx

Documentation Problems

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

If you discover any errors in or have any problems with this documentation, please email us by following the instructions below. Describe the error or problem as completely as possible and give us the document title, the date of the document (located at the foot of every page), and the page number or page range.

To contact Customer Service about documentation problems:

1. Go to

https://www.paypal.com/.

2. Click Help in the upper left corner of the page.

3. Click Contact Us in the lower left of the page.

4. Choose Help by Email.

5. Complete the form.

10 August 2005 Order Management Integration Guide

Email

Introduction

PayPal offers four payment notification methods for backend integration:

z Email z Reporting To ols z Instant Payment Notification (IPN) z Payment Data Transfer (PDT)

You will receive an email notification in the following cases:

z Successful Payment z Pending Payment z Cancelled Payment

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

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

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

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

4. Click Save.

Reporting

PayPal’s Reporting Tools provide you with the information you n eed to effectively measure and manage your business. With PayPal’s Reporting Tools, you can:

z Analyze your revenue sources to better understand your customers’ buying behavior z Automate time-consuming bookkeeping tasks z Accurately settle and reconcile transactions

Available reports:

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

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

Payments and Instant Purchase checkbox.

affected your account balance each month.

channel and currency.

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

Order Management Integration Guide August 2005 11

Introduction

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

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

various file formats (suitable for financial settlements).

For more information about PayPal's reports, see

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

http://www.paypal.com/cgi-

Differences between Instant Payment Notification (IPN) and

Payment Data Transfer (PDT)

PDT's primary function is to display payment transaction details to buyers when they are automatically redirected back to your site upon payment completion; however, there are cases where you will not receive notification of all transactions, such as with pending transactions, refunds, and reversals. For these reasons, or if you are using this data to fulfill orders, PayPal strongly recommends that you also enable Instant Payment Notification (IPN).

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

z Requires Auto Return to be enabled. z Auto Return will include an ID that can be used to query PayPal for the complete

transaction details.

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

complete.

IPN:

z Does not require Auto Return to be enabled. z At the end of the website payment flow, PayPal POSTs the IPN data asynchronously (i.e.

not as part of the website payment flow).

z IPNs will also POST for eCheck clearings, reversals, and refunds.

SSL Not Required for IPN

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

12 August 2005 Order Management Integration Guide

PayPal-Supported Currencies

The following currencies are supported by PayPal.

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

Transaction Amounts

Code Currency

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

Introduction

PayPal-Supported Currencies

Maximum Transaction Amount

Order Management Integration Guide August 2005 13

Introduction

PayPal-Supported Currencies

14 August 2005 Order Management Integration Guide

Payment Data Transfer

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

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

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

How PDT Works

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

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

Order Management Integration Guide August 2005 15

Payment Data Transfer

How PDT Works

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

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

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

16 August 2005 Order Management Integration Guide

Payment Data Transfer

How PDT Works

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

Step 6: A transaction token is passed to the return URL provided by the Widget Warehouse. The Widget Warehouse fetches the transaction token and retrieves the transaction details from PayPal via an HTTP POST. Included in the HTTP post is the identity token that was given to the Widget Warehouse when PDT was enabled.

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

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

Step 7: The Widget Warehouse's Thank You page appears and displays the transaction information, again informing Bob that his transaction has been completed and a receipt for the purchase has been emailed to him. The page also displays payment details, a link to PayPal that Bob can use to view more transaction details if necessary, as well as links that he can use to continue shopping.

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

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

Order Management Integration Guide August 2005 17

Payment Data Transfer

Enabling Payment Data Transfer

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

Enabling Payment Data Transfer

To enable PDT:

1. Click the My Account tab.

2. Click the Profile subtab.

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

The Website Payment Preferences page opens.

18 August 2005 Order Management Integration Guide

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

NOTE: You must enable Auto Return in order to use Payment Data Transfer. Auto Return can

also be enabled from the Website Payment Preferences page.

5. Click Save.

Getting and Using the Identity Token

When you click Save and save your PDT preferences, a message appears at the top of the page indicating that you have successfully saved your preferences. Your identity token also appears in this message.

Payment Data Transfer

PDT and PayPal Account Optional

You will need to pass this identity token, along with the transaction token, to PayPal in order to receive information that confirms that a payment is complete.

For security, the identity token is not sent to you; however, once you have enabled PDT, it permanently appears below the Payment Data Transfer On/Off radio buttons on the Website Payments Preferences page.

PDT and PayPal Account Optional

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

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

Order Management Integration Guide August 2005 19

Payment Data Transfer

PDT Notification Synch

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

PDT Notification Synch

After you have activated PDT, every time a buyer makes a website payment and is redirected to your return URL, a transaction token is sent via a FORM GET variable to this return URL.

To properly use PDT and display transaction details to your customer, you should read the transaction token from the variable tx and retrieve transaction details from PayPal by constructing an HTTPS POST to PayPal. This is called notification synch or synchronization.

Constructing the POST

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

1. Your POST must be sent to

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

cmd=_notify-synch

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

token received via PayPal’s GET:

value_of_transaction_token

tx=

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

token:

at=

your_identity_token

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

page 19.

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

20 August 2005 Order Management Integration Guide

PayPal Response to POST

PayPal responds to the post with a single word on one line in the body of the response: SUCCESS or FAIL. When you receive a SUCCESS response, the rest of the body of the response is the transaction details, one per line, in the format both be URL-encoded strings. This response data needs to be parsed appropriatel y and then URL-decoded.

Example successful response:

SUCCESS first_name=Jane+Doe last_name=Smith payment_status=Completed payer_email=janedoesmith%40hot mail.com payment_gross=3.99 mc_currency=USD custom=For+the+purchase+of+the +rare+book+Green+E ggs+%26+Ham ...

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

Payment Data Transfer

PDT Notification Synch

key=value where key and value are

z The Transaction token is not bad. z The ID token is not bad. z The tokens have not expired.

PDT and Auto Return: Messaging to Buyer

When Auto Return, you must display a message on the page displayed by the Return URL that helps the buyer understand that the payment has been made, that the transaction has been completed, and that payment transaction details will be emailed to the buyer. You can display to your customer whatever payment details you feel are appropriate; however, PayPal recommends including the following:

z Item name z Amount paid z Payer email z Shipping address

If you are using PDT to determine when to fulfill an order automatically, confirm that the payment_status is Completed, since the buyer could use methods such as echecks that do not immediately clear.

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

Order Management Integration Guide August 2005 21

Payment Data Transfer

Preventing Fraud

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

z txn_id is not a duplicate to prevent someone from reusing an old, completed transaction. z receiver_email is an email address registered in your PayPal account, to prevent the

payment from being sent to a fraudulent account.

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

not been changed.

Code Samples

PayPal has made available code samples that you can use to set up PDT. These samples are available at

There are code samples for the following development environments:

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

z ASP/VBScript z ColdFusion z PERL z PHP

22 August 2005 Order Management Integration Guide

Instant Payment Notification

(IPN)

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

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

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

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

How It Works

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

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

Order Management Integration Guide August 2005 23

+ 51 hidden pages