PayPal Instant Payment Notification - 2009 User Guide

Instant Payment Notification Guide

For Professional Use Only Currently only available in English.

A usage Professional Uniquement Disponible en Anglais uniquement pour l’instant.

Last updated: June 26, 2009

IPN Guide

Document Number: 10087.en_US-20090626

© 2009 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners. The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc. 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. 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.

Contents

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 1 Introducing IPN . . . . . . . . . . . . . . . . . . . . . . . 7

What is IPN? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

IPN Protocol and Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

IPN Messages Generated by Website Payments Standard . . . . . . . . . . . . . . . 10

IPN Messages Generated by PayPal APIs . . . . . . . . . . . . . . . . . . . . . . . 11

IPN Messages Generated by a Back-Office Procedure . . . . . . . . . . . . . . . . . 12

IPN Messages Generated by PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . 13

A Sample IPN Message and Response . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Non-IPN Notification Mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 2 Implementing an IPN Listener . . . . . . . . . . . . . . . .19

Chapter 3 Identifying Your IPN Listener to PayPal . . . . . . . . . . .23

Setting Up IPN Notifications on PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Dynamically Setting the Notification URL . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Chapter 4 IPN Testing . . . . . . . . . . . . . . . . . . . . . . . . .27

Testing Your Listener. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

IPN Troubleshooting Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Chapter 5 IPN Operations on PayPal . . . . . . . . . . . . . . . . . .31

Using the IPN History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Resending IPN Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Chapter 6 Using Fraud Management Filters With IPN . . . . . . . . . 37

Chapter 7 IPN Variable Reference . . . . . . . . . . . . . . . . . . .41

IPN Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

IPN Guide June, 2009 3

Contents

Transaction and Notification-Related Variables . . . . . . . . . . . . . . . . . . . . . . . 42

Buyer Information Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Payment Information Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Auction Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Mass Pay Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Recurring Payments Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Subscription Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Dispute Resolution Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Payment Review Using Notifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

4 June, 2009 IPN Guide

Preface

This document describes the Instant Payment Notification (IPN) message service.

Intended Audience

This document is intended for merchants implementing IPN.

Revision History

Revision history for Instant Payment Notification Guide.

TABLE P.1 Revision History

Date Description

06/26/09 Added information about IPN messages related to payment review. Updated the

section about setting up IPN notifications on PayPal and added a note about the delivery of IPN messages to the notify URL.

06/10/09 Added IPN history and resend information and added information to the

troubleshooting section.

03/16/09 Made additions to sample code.

02/16/09 First draft.

IPN Guide June, 2009 5

Revision History

6 June, 2009 IPN Guide

Instant Payment Notification (IPN) is a message service that notifies you of events related to PayPal transactions. You can use it to automate back-office and administrative functions, such as fulfilling orders, tracking customers, and providing status and other information related to a transaction.

z What is IPN?

z IPN Protocol and Architecture

z A Sample IPN Message and Response

z Non-IPN Notification Mechanisms

What is IPN?

IPN notifies you when an event occurs that affects a transaction. Typically, these events represent various kinds of payments; however, the events may also represent authorizations, Fraud Management Filter actions and other actions, such as refunds, disputes, and chargebacks.

Introducing IPN

IPN is a message service that PayPal uses to notify you about events. These events include the following:

z Instant payments, including Express Checkout and direct credit card payments

z eCheck payments and associated status, such as pending, completed, or denied

z Payments that may be pending for other reasons, such as those being reviewed for potential

fraud

z Events related to recurring payments and subscriptions

z Authorizations, which indicate a sale whose payment has not yet been collected

z Chargebacks, which are initiated by a credit card processor; for example, when a customer

disputes a charge

z Disputes, which are initiated by a buyer using the PayPal resolution process

z Reversals, which occur when you win a dispute or a chargeback is canceled

z Refunds, which you may choose to give

In many cases, the action that causes the event, such as a payment, occurs on your website; however, your website is not the only source of events. In many cases, events can be generated by Website Payment Standard buttons, the PayPal API, or by PayPal itself.

You detect and process IPN messages with a listener, sometimes called a handler, which is a script or program that you write. It waits for messages and passes them to various back-end or

IPN Guide June, 2009 7

Introducing IPN

What is IPN?

administrative processes that respond the messages. PayPal provides sample code that you can modify to implement a listener that detects IPN messages.

The actions to take when your listener is notified of an event are specific to your needs. Examples of the kinds of actions you might take when your listener receives an IPN message include the following:

z Trigger order fulfillment or enable media downloads when a check clears or a payment is

made

z Update your list of customers

z Update accounting records

z Create specialized “to do” lists based on the kind of event

You are typically notified of events by email as well, but the IPN message service enables you to automate your response to events. The following diagram shows how events can occur and how PayPal responds with IPN messages that it sends to your listener:

The diagram shows requests and responses, which are the result of processing button clicks or API operations on PayPal. PayPal sends an IPN message when it sends a response to a request.

8 June, 2009 IPN Guide

Introducing IPN

IPN Protocol and Architecture

The IPN message is not actually part of the response sent to your website. Rather, the IPN message is sent to the your listener, which allows you to take actions that are not directly tied to the operation of your website.

NOTE: The diagram does not show the IPN authentication protocol messages that validate the

IPN message.

IPN is an asynchronous message service, meaning that messages are not synchronized with actions on your website. Thus, listening for an IPN message does not increase the time it takes to complete a transaction on your website.

The IPN message service does not assume that all messages will be received by your listener in a timely manner. Because the internet is not 100% reliable, messages can become lost or delayed. To handle the possibility of transmission and receipt delays or failures, the IPN message service implements a retry mechanism that resends messages at various intervals until you acknowledge that the message has successfully been received. Messages may be resent for up to four days after the original message.

NOTE: Unless you are certain that a failure occurred on the the Internet, the most likely cause

of lost, delayed, or duplicate IPN messages is faulty logic in the listener itself.

Because messages can be delivered at any time, your listener must always be available to receive and process messages; however, the retry mechanism also handles the possibility that your listener could become swamped or stop responding.

The IPN message service should not be considered a real-time service. Your checkout flow should not wait on an IPN message before it is allowed to complete. If your website waits for an IPN message, checkout processing may be delayed due to system load and become more complicated because of the possibility of retries.

IPN Protocol and Architecture

IPN is designed to be secure, reliable, and asynchronous. To meet these requirements, the protocol requires you to acknowledge receipt of IPN messages. The IPN service provides a retry mechanism to handle cases in which a message is not acknowledged; for example, when a transmission or receipt failure occurs.

When you enable IPN, PayPal sends messages to the IPN listener at the URL you specify in your account’s profile. You can override the URL to associate other IPN listeners with specific transactions. In this case, you specify the listener’s URL when you set up a Website Payment Standard button or a PayPal API operation.

The IPN protocol consists of three steps:

1. PayPal sends your IPN listener a message that notifies you of the event

2. Your listener sends the complete unaltered message back to PayPal; the message must

contain the same fields in the same order and be encoded in the same way as the original message

IPN Guide June, 2009 9

Introducing IPN

IPN Protocol and Architecture

3. PayPal sends a single word back, which is either VERIFIED if the message originated with PayPal or INVALID if there is any discrepancy with what was originally sent

Your listener must respond to each message, whether or not you intend to do anything with it. If you do not respond, PayPal assumes that the message was not received and resends the message. PayPal continues to resend the message periodically until your listener sends the correct message back, although the interval between resent messages increases each time. The message can be resent for up to four days.

This resend algorithm can lead to situations in which PayPal resends the IPN message while you are sending back the original message. In this case, you should send your response again, to cover the possibility that PayPal did not actually receive your response the first time. You should also ensure that you do not process the transaction associated with the message twice.

IMPORTANT: PayPal expects to receive a response to an IPN message within 30 seconds.

After PayPal verifies the message, there are additional checks that your listener or back-end or administrative software must take:

Your listener should not perform time-consuming operations, such as creating a process, before responding to the IPN message.

z Verify that you are the intended recipient of the IPN message by checking the email address

in the message; this handles a situation where another merchant could accidentally or intentionally attempt to use your listener.

z Avoid duplicate IPN messages. Check that you have not already processed the transaction

identified by the transaction ID returned in the IPN message. You may need to store transaction IDs returned by IPN messages in a file or database so that you can check for duplicates. If the transaction ID sent by PayPal is a duplicate, you should not process it again.

z Because IPN messages can be sent at various stages in a transaction’s progress, make sure

that the transaction’s payment status is “completed” before enabling shipment of merchandise or allowing the download of digital media.

z Verify that the payment amount actually matches what you intend to charge. Although not

technically an IPN issue, if you do not encrypt buttons, it is possible for someone to capture the original transmission and change the price. Without this check, you could accept a lesser payment than what you expected.

IPN Messages Generated by Website Payments Standard

PayPal generates an IPN message when your customer clicks a Website Payments Standard payment button, such as a Buy Now button, and completes the transaction on PayPal. You can use this notification to kick-off order fulfillment, enable digital media downloads, store information in a customer relationship management (CRM) or accounting system, and so on.

The following diagram shows both the web flow and the IPN message authentication protocol:

10 June, 2009 IPN Guide

The numbers in diagram correspond to the following steps:

Introducing IPN

IPN Protocol and Architecture

1. The button action initiates a payment that completes on PayPal

2. PayPal sends your IPN listener a message that notifies you of the event

3. Your listener sends the complete unaltered message back to PayPal; the message must

contain the same fields in the same order and be encoded in the same way as the original message

4. PayPal sends a single word back, which is either VERIFIED if the message originated with PayPal or INVALID if there is any discrepancy with what was originally sent

Your IPN listener must implement the IPN authentication protocol (steps 2, 3, and 4 in this diagram). After successfully completing the protocol, your back-office or administrative process vets the contents of the message and responds appropriately. For example, if the payment status for the transaction is “Completed,” your system can print a packing list or email a password to your customer for downloading digital media.

IPN Messages Generated by PayPal APIs

PayPal generates an IPN message when you invoke an API operation, such as DoExpressCheckoutPayment of DoDirectPayment during checkout. You can use this notification to kick-off order fulfillment, enable digital media downloads, store information in a customer relationship management (CRM) or accounting system, and so on.

The following diagram shows both the web flow and the IPN message authentication protocol:

IPN Guide June, 2009 11

Introducing IPN

IPN Protocol and Architecture

The numbers in diagram correspond to the following steps:

1. The API operation initiates a payment on PayPal.

2. PayPal sends your IPN listener a message that notifies you of the event

3. Your listener sends the complete unaltered message back to PayPal; the message must

contain the same fields in the same order and be encoded in the same way as the original message

4. PayPal sends a single word back, which is either VERIFIED if the message originated with PayPal or INVALID if there is any discrepancy with what was originally sent

IPN Messages Generated by a Back-Office Procedure

PayPal generates an IPN message when you perform actions that invoke the PayPal API, regardless of whether it is from your website or from a back-office or administrative procedure. You can use this notification to trigger an email to your customer, store information in a CRM or accounting system, and so on.

The following diagram shows both an administrative web flow and the IPN message authentication protocol:

12 June, 2009 IPN Guide

The numbers in diagram correspond to the following steps:

Introducing IPN

IPN Protocol and Architecture

1. Your back-office or administrative process invokes a PayPal API operation; for example, it could invoke the RefundTransaction API operation when your employee issues a refund.

2. PayPal sends your IPN listener a message that notifies you of the event

3. Your listener sends the complete unaltered message back to PayPal; the message must

contain the same fields in the same order and be encoded in the same way as the original message

4. PayPal sends a single word back, which is either VERIFIED if the message originated with PayPal or INVALID if there is any discrepancy with what was originally sent

Your IPN listener implements the IPN authentication protocol (steps 2, 3, and 4 in this diagram). After successfully completing the protocol, your listener or back-office or administrative process vets the contents of the message and responds appropriately. For example, your system can notify the customer of the refund by email.

IPN Messages Generated by PayPal

Some IPN messages generated by PayPal are not directly associated with a web flow. PayPal generates an IPN message when external events arise that might affect a transaction, such as disputes, chargebacks, echeck clearing, and various recurring payment and subscription events.

In this case, events that trigger IPN messages are not directly related to actions on your website. The following diagram shows the steps your listener must take:

IPN Guide June, 2009 13

Introducing IPN

A Sample IPN Message and Response

The numbers in diagram correspond to the following steps, which implement the IPN message authentication protocol:

1. PayPal sends your IPN listener a message that notifies you of the event

2. Your listener sends the complete unaltered message back to PayPal; the message must

contain the same fields in the same order and be encoded in the same way as the original message

3. PayPal sends a single word back, which is either VERIFIED if the message originated with PayPal or INVALID if there is any discrepancy with what was originally sent

After successfully completing the protocol, your back-office or administrative process vets the contents of the message and responds appropriately. For example, the IPN messages may trigger you to print shipping labels for items whose payments have cleared, investigate disputes and chargebacks, store information in an accounting system, and so on.

A Sample IPN Message and Response

An IPN message consists of variables that describe the transaction. These variables contain information about you, your customer, and the details of the transaction itself.

PayPal sends a message, similar to the following one, for a $19.95 purchase made by Express Checkout:

14 June, 2009 IPN Guide

Introducing IPN

A Sample IPN Message and Response

mc_gross=19.95&protection_eligibility=Eligible&address_status=confirmed&pay er_id=LPLWNMTBWMFAY&tax=0.00&address_street=1+Main+St&payment_date=20%3A12% 3A59+Jan+13%2C+2009+PST&payment_status=Completed&charset=windows1252&address_zip=95131&first_name=Test&mc_fee=0.88&address_country_code=US& address_name=Test+User¬ify_version=2.6&custom=&payer_status=verified&add ress_country=United+States&address_city=San+Jose&quantity=1&verify_sign=Atk OfCXbDm2hu0ZELryHFjY-Vb7PAUvS6nMXgysbElEn9v1XcmSoGtf&payer_email=gpmac_1231902590_per%40paypal.com&txn_id=61E67681CH32 38416&payment_type=instant&last_name=User&address_state=CA&receiver_email=g pmac_1231902686_biz%40paypal.com&payment_fee=0.88&receiver_id=S8XGHLYDW9T3S &txn_type=express_checkout&item_name=&mc_currency=USD&item_number=&residenc e_country=US&test_ipn=1&handling_amount=0.00&transaction_subject=&payment_g ross=19.95&shipping=0.00

Variabl e Notes

Information about you:

receiver_email = gm_1231902686_biz@paypal.com Check email address to make sure that this is not a spoof

receiver_id = S8XGHLYDW9T3S

residence_country = US

Information about the transaction:

test_ipn = 1 Testing with the Sandbox

transaction_subject =

txn_id = 61E67681CH3238416 Keep this ID to avoid processing the transaction twice

txn_type = express_checkout Type of transaction

Information about your buyer:

payer_email = gm_1231902590_per@paypal.com

payer_id = LPLWNMTBWMFAY

payer_status = verified

first_name = Test

last_name = User

address_city = San Jose

address_country = United States

address_country_code = US

address_name = Test User

address_state = CA

address_status = confirmed

IPN Guide June, 2009 15

Introducing IPN

A Sample IPN Message and Response

Variabl e Notes

address_street = 1 Main St

address_zip = 95131

Information about the payment:

custom = Your custom field

handling_amount = 0.00

item_name =

item_number =

mc_currency = USD

mc_fee = 0.88

mc_gross = 19.95

payment_date = 20:12:59 Jan 13, 2009 PST

payment_fee = 0.88

payment_gross = 19.95

payment_status = Completed Status, which determines whether the transaction is

complete

payment_type = instant Kind of payment

protection_eligibility = Eligible

quantity = 1

shipping = 0.00

tax = 0.00

Other information about the transaction:

notify_version = 2.6 IPN version; can be ignored

charset = windows-1252

verify_sign = AtkOfCXbDm2hu0ZELryHFjYVb7PAUvS6nMXgysbElEn9v-1XcmSoGtf

Before you can trust the contents of the message, you must first verify that the message came from PayPal. To verify the message, you must send back the contents in the exact order they were received and precede it with the command _notify-validate, as follows:

https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_notifyvalidate&mc_gross=19.95&protection_eligibility=Eligible&address_status=conf irmed&payer_id=LPLWNMTBWMFAY&tax=0.00&...&payment_gross=19.95&shipping=0.00

16 June, 2009 IPN Guide

PayPal will then send one single-word message, VERIFIED, if the message is valid; otherwise, it will send another single-word message, INVALID.

IMPORTANT: After you receive the VERIFIED message, there are several important checks

you must perform before you can assume that the message is legitimate and not already processed:

Confirm that the payment status is Completed.

Use the transaction ID to verify that the transaction has not already been processed, which prevents duplicate transactions from being processed.

Validate that the receiver’s email address is registered to you.

Verify that the price, item description, and so on, match the transaction on your website.

Non-IPN Notification Mechanisms

You can use IPN with other notification mechanisms. For example, you can use PDT or the API to determine real-time information about a transaction and let IPN notify you of any changes after the transaction occurs.

Introducing IPN

Non-IPN Notification Mechanisms

If you are using Website Payments Standard, you can use PDT to obtain information about the transaction. If you are using Express Checkout or Direct Payment, the PayPal API notifies you of the status and details of the transaction immediately and automatically. In either case, you can immediately display to your customer the information being returned from PayPal. You should not use IPN for this purpose.

IPN Guide June, 2009 17

Introducing IPN

Non-IPN Notification Mechanisms

18 June, 2009 IPN Guide

+ 42 hidden pages