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.

This chapter details IPN in the following sections:

l	“About IPN”

l	“Setting Up IPN””

l	“Using IPN Notification Validation to Help Prevent Fraud””

l	“Using IPN with Multiple Currencies””

l	“Dispute Notification and Downloadable Dispute Report”

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.

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:

l	“Activating IPN for Your PayPal Account”

l	“Setting Up an IPN-Processing Program”

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.

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:

l	See the Name-Value Pair API Developer Guide and Reference

– or –

l	See 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:

l	ASP.Net/C#

l	ASP/VBScript

l	ColdFusion

l

Java/JSP

l

Perl

l

PHP

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:

l	Use 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”.

l	Send 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”.

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.

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.

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

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.

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

Note:

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

l	mc_fee: Transaction fee associated with the payment. Variable function like payment_fee variable (variable does not appear when payment pending, and so on).

Note:

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

l	mc_currency: Currency of mc_gross, mc_fee, payment_gross, and payment_fee amounts. Possible values are detailed in “”.

l	For 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:

l	mc_gross = payment_gross

l	mc_fee = payment_fee

Example 3.1

Multi-currency IPN: USD Payment

payment_status = Completed

payment_gross = 100

payment_fee = 3.00

mc_gross = 100

mc_fee = 3.00

mc_currency = USD

Example 2

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

l	mc_gross and mc_fee have values.

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

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:

l	Complaint: A buyer has used the PayPal Resolution Center to register a claim about a payment to a merchant.

Note:

After notification about a complaint claim, merchants must log in to PayPal to use the Resolution Center to respond to the case.

l	Chargeback: A buyer has filed a complaint with a credit card company that has resulted in a chargeback. The credit card company notifies PayPal about the reason for the chargeback. After investigating the case, PayPal notifies the merchant of any action required.

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

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:

l

New cases

l	Changed cases, including cases that are closed

Setup

To use the report you must:

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=”day” VALUE=”16”>

<INPUT TYPE=”hidden” NAME=”month” VALUE=”09”>

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

<INPUT TYPE=”hidden” NAME=”uname” VALUE=”yourAliasUsername”>

<INPUT TYPE=”hidden” NAME=”pword” VALUE=”yourAliasPassword”>

<INPUT TYPE=”image” VALUE=”Submit”>

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